部署指南

这是运维文档，和课程学习内容无关。如果你是来学习 AI 应用开发的读者，直接从 课程主线 开始即可，不需要阅读这页。 进度记录功能（用户注册/登录、按章节记录进度）为站点内部功能，当前不向读者开放。读者直接阅读文档内容即可，无需登录或注册账号。 注意：后端进度接口代码仍保留，但 /api/progress/meta 目前还按旧的 docs/curriculum/ 目录统计章节数，和当前 app-dev/、vibe-coding/ 路线不完全匹配。除非后续重新整理进度系统，否则不要把登录/进度功能作为公开能力依赖。

本站支持用户注册/登录并记录各章节学习进度，后端使用 Hono + SQLite，通过 Docker Compose 部署，IIS 作为外层反向代理处理域名和 SSL。

架构说明

外部访问 ai-learning.superzou.vip（80/443）
        ↓
      IIS（处理 SSL 证书、域名绑定）
        ↓ 反向代理到本机 8080
    Docker nginx 容器（:8080，serve 静态文件 + 转发 /api）
        ↓
    Docker api 容器（:9001，Hono + SQLite）

IIS 负责对外的域名和 HTTPS，Docker 内部的 nginx 负责静态文件服务和 API 路由，两者职责分离。

前置要求

• Windows Server 已安装 Docker Desktop（需开启 WSL2 后端）
• 服务器已安装 Node.js 20+ 和 npm（用于本地构建前端）
• IIS 已安装以下两个免费模块：
  • URL Rewrite
  • Application Request Routing (ARR)

部署步骤

1. 克隆代码到服务器

git clone <你的仓库地址>
cd ai-learning

2. 配置环境变量

copy .env.example .env

打开 .env，修改以下内容：

JWT_SECRET=my-super-secret-random-key-2026
NGINX_PORT=8080

注意：JWT_SECRET 一旦设置后不要修改，否则所有已登录用户的 token 会失效。

3. 构建前端静态文件

npm install
npm run docs:build

构建产物生成在 docs/.vitepress/dist/，由 Docker nginx 容器直接 serve。

4. 启动 Docker 服务

docker compose up -d --build

首次构建约需 1-2 分钟。完成后可先通过 http://localhost:8080 验证：

curl http://localhost:8080/api/health
# 期望返回：{"status":"ok"}

5. 配置 IIS 反向代理

5.1 启用 ARR 代理

打开 IIS 管理器 → 选择服务器节点 → 双击 Application Request Routing Cache → 点击右侧 Server Proxy Settings → 勾选 Enable proxy → 点击 Apply。

5.2 新建网站

在 IIS 管理器中新建一个网站，绑定你的子域名（如 ai-learning.superzou.vip），物理路径随意指定一个空目录即可（实际内容由反代提供）。

5.3 添加 URL Rewrite 规则

在该网站下，双击 URL Rewrite → 点击右侧 Add Rule(s) → 选择 Reverse Proxy，填写：

Server name (or IP address): localhost:8080

勾选 Enable SSL Offloading（如果 IIS 处理了 HTTPS），点击 OK。

这条规则会自动生成 web.config，内容类似：

<system.webServer>
  <rewrite>
    <rules>
      <rule name="ReverseProxy" stopProcessing="true">
        <match url="(.*)" />
        <action type="Rewrite" url="http://localhost:8080/{R:1}" />
      </rule>
    </rules>
  </rewrite>
</system.webServer>

5.4 绑定 SSL 证书（可选）

在网站绑定中添加 HTTPS（443 端口），选择你的证书（可用 win-acme 申请免费 Let's Encrypt 证书）。

绑定 HTTPS 后，将 .env 中的 CORS_ORIGIN 改为你的域名：

CORS_ORIGIN=https://ai-learning.superzou.vip

然后重启 API 容器：

docker compose up -d api

数据持久化

SQLite 数据库文件位于 data/progress.db，通过 Docker volume 挂载到宿主机，重建容器数据不丢失。

备份：

copy data\progress.db data\progress.db.bak

日常更新

更新文档内容（只改 Markdown）：

npm run docs:build
docker compose restart nginx

更新后端代码：

docker compose up -d --build api

常见问题

8080 端口被占用：修改 .env 中的 NGINX_PORT 为其他端口，IIS 反代规则里也同步修改。

忘记密码：目前暂无找回密码功能，可通过容器内 SQLite 查看用户列表：

docker compose exec api sh
sqlite3 /app/data/progress.db "SELECT id, email, nickname FROM users;"

查看运行日志：

docker compose logs api
docker compose logs nginx

目录结构

ai-learning/
├── server/              # 后端代码（Hono + SQLite）
│   └── src/
│       ├── index.js     # 主入口
│       ├── db.js        # 数据库初始化
│       ├── auth.js      # 注册/登录接口
│       └── progress.js  # 进度接口（防倒退逻辑）
├── docs/
│   └── .vitepress/
│       └── theme/       # 自定义 Vue 组件（登录浮层、进度条）
├── data/                # SQLite 数据库（运行后自动创建，不提交 git）
├── Dockerfile.api       # API 容器镜像
├── docker-compose.yml   # 服务编排
├── nginx.conf           # 容器内 Nginx 配置
├── .env.example         # 环境变量模板
└── .env                 # 本地配置（不提交 git）