# Duoqi Admin 部署方案 > 基于 duoqi-api 现有 Gitea + 阿里云轻量应用服务器基础设施，零额外内存的纯前端部署方案 ## 目录 - [架构概览](#架构概览) - [资源规划](#资源规划) - [服务器端准备](#服务器端准备) - [Nginx 配置](#nginx-配置) - [HTTPS 证书](#https-证书) - [DNS 配置](#dns-配置) - [前端环境变量](#前端环境变量) - [CI/CD 流程](#cicd-流程) - [部署验证](#部署验证) - [API 代理方案对比](#api-代理方案对比) - [服务器端目录结构](#服务器端目录结构) - [运维管理](#运维管理) - [故障排查](#故障排查) --- ## 架构概览 ### 核心设计 duoqi-admin 是纯前端 SPA，不需要 Docker，直接由 Nginx 托管静态文件。零额外内存开销，复用 duoqi-api 已有的 Gitea + Nginx + Act Runner 基础设施。 ### 为什么不套 Docker 当前服务器 2GB 内存已用约 1.1GB。静态站点用 Docker 是浪费——Nginx 本身已在运行，直接加一个 `server` 块托管 `dist/` 即可，内存增量约等于 0。这也符合 duoqi-api 部署文档中"每 MB 都有意义"的设计原则。 ### 架构图 ``` ┌─────────────────────────────────────────────────────────────────────┐ │ 阿里云轻量应用服务器 (2C/2G) │ │ │ │ ┌───────────────────────────────────────────────────────────────┐ │ │ │ Nginx 反向代理 (:80/:443) │ │ │ │ ┌────────────┐ ┌──────────────┐ ┌────────┐ ┌──────────────┐ │ │ │ │ │api.duoqi.me│ │test-api. │ │git. │ │admin.duoqi.me│ │ │ │ │ │→ :3000 prod│ │duoqi.me │ │duoqi.me│ │→ 静态文件 │ │ │ │ │ │ │ │→ :3001 test │ │ │ │/opt/duoqi- │ │ │ │ │ │ │ │ │ │ │ │admin/dist/ │ │ │ │ │ └────────────┘ └──────────────┘ └────────┘ └──────────────┘ │ │ │ └───────────────────────────────────────────────────────────────┘ │ │ │ │ ┌─────────────┐ ┌──────────────┐ ┌──────────────────────────┐ │ │ │ duoqi-api │ │ duoqi-api │ │ Gitea + Act Runner │ │ │ │ (prod) │ │ (test) │ │ + duoqi-admin 仓库 │ │ │ │ :3000 │ │ :3001 │ │ CI/CD: build → copy │ │ │ └─────────────┘ └──────────────┘ └──────────────────────────┘ │ │ │ │ ┌───────────────────────────────────────────────────────────────┐ │ │ │ /opt/duoqi-admin/dist/ ← 构建产物（纯静态文件） │ │ │ └───────────────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────────┘ ``` --- ## 资源规划 ### 内存增量：约 0MB | 组件 | 新增占用 | 说明 | |------|----------|------| | Nginx server 块 | ~0MB | Nginx 已运行，静态文件不占额外进程内存 | | dist/ 磁盘 | ~5-10MB | Vite 构建产物极小 | | CI/CD | ~0MB | 复用已有 Act Runner | ### DNS 记录 | 子域名 | 类型 | 值 | |--------|------|----| | admin.duoqi.me | A | 服务器公网 IP | --- ## 服务器端准备 ```bash # 创建部署目录 mkdir -p /opt/duoqi-admin/dist # 设置初始占位页面（首次部署前） cat > /opt/duoqi-admin/dist/index.html << 'EOF'

Duoqi Admin - Deploying...

EOF ``` --- ## Nginx 配置 创建配置文件 `/etc/nginx/conf.d/duoqi-admin.conf`： ```nginx server { listen 80; server_name admin.duoqi.me; # 限制访问 IP（仅管理员网络，上线后取消注释） # allow 123.56.78.90; # deny all; root /opt/duoqi-admin/dist; index index.html; # SPA 路由回退 — 所有未匹配路径返回 index.html location / { try_files $uri $uri/ /index.html; } # API 代理 — 转发到后端生产环境 location /admin/ { proxy_pass http://localhost:3000; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } # 静态资源缓存（Vite 带 hash 的文件） location /assets/ { expires 1y; add_header Cache-Control "public, immutable"; } # 安全头 add_header X-Frame-Options "SAMEORIGIN" always; add_header X-Content-Type-Options "nosniff" always; } ``` 验证并生效： ```bash nginx -t systemctl reload nginx ``` > **`try_files` 说明**：React Router 的前端路由（如 `/questions`、`/categories`）在浏览器刷新时会向服务器请求这些路径。没有 `try_files` 回退，Nginx 会返回 404。有了它，所有未知路径都回退到 `index.html`，由前端 JS 路由接管。`/assets/` 目录下的文件由 Vite 自动添加 content hash（如 `assets/index-DK2R8j.css`），可以安全设置 1 年强缓存。 --- ## HTTPS 证书 将 admin.duoqi.me 加入已有证书（注意 `--expand` 必须列出所有域名）： ```bash sudo certbot --nginx --expand \ -d api.duoqi.me -d test-api.duoqi.me -d git.duoqi.me -d admin.duoqi.me # 验证自动续期 certbot renew --dry-run ``` ### `--expand` 注意事项 > **来自 duoqi-api 部署实操的经验**： 1. **DNS 必须先生效**：`--expand` 要求新域名的 DNS 已指向服务器且可公网访问，否则 certbot 的 HTTP-01 验证会失败。 2. **必须列出所有域名**：`--expand` 是替换整张证书，不是追加。 ```bash # ❌ 错误：只写新增域名，会导致原有域名被移除！ sudo certbot --nginx --expand -d admin.duoqi.me # ✅ 正确：列出所有域名（原有 + 新增） sudo certbot --nginx --expand \ -d api.duoqi.me -d test-api.duoqi.me -d git.duoqi.me -d admin.duoqi.me ``` 3. **备案问题**：阿里云服务器 + 未备案域名，HTTP 请求可能被运营商层拦截（返回 403，`Server: Beaver`），导致 certbot 验证失败。需要先完成 ICP 备案，或暂时使用其他验证方式（DNS-01）。 --- ## DNS 配置 在域名管理后台添加 A 记录： | 主机记录 | 记录类型 | 记录值 | |----------|----------|--------| | admin | A | 服务器公网 IP | --- ## 前端环境变量 构建时需指向生产 API。推荐使用 Nginx 代理方案，构建时 `VITE_API_BASE_URL` 留空： ```env # .env.production VITE_API_BASE_URL= ``` 这样 `ky` 的请求会发到 `admin.duoqi.me/admin/*`，由 Nginx 转发到 `localhost:3000`，无跨域问题。 如果使用直连方案（不推荐）： ```env # .env.production（直连方案） VITE_API_BASE_URL=https://api.duoqi.me ``` --- ## CI/CD 流程 ### 前置条件：Runner 基础设施 > duoqi-admin 复用 duoqi-api 已搭建的 Gitea + Act Runner 基础设施。 > 以下配置需要在 Runner 端**一次性完成**，不需要每次部署时重复操作。 #### 1. Runner 配置文件更新 Runner 的 job 容器需要能访问 `/opt/duoqi-admin` 目录。编辑 `/opt/act-runner/config.yaml`： ```yaml container: # 容器使用宿主机网络（继承自 duoqi-api 配置） network: "host" # 在原有挂载基础上，增加 admin 目录 options: "-v /opt/duoqi-api:/opt/duoqi-api -v /opt/duoqi-admin:/opt/duoqi-admin" # 在原有白名单基础上，增加 admin 目录 valid_volumes: - /opt/duoqi-api - /opt/duoqi-admin # 不强制每次拉取镜像（国内网络下减少失败风险） force_pull: false ``` 修改后重启 Runner： ```bash systemctl restart act-runner ``` > **为什么不用 SSH/rsync**：Act Runner 的 job 容器通过 `network: host` + volume 挂载直接访问宿主机文件系统，无需 SSH 跳转。SSH 方式在容器内需要额外配置密钥，反而更复杂。 #### 2. 自定义 Runner 镜像 Runner 使用自定义镜像 `duoqi-runner:bun-git`（基于 `oven/bun` + git + docker CLI）。该镜像： - **包含**：bun、git（checkout 需要）、docker CLI - **不包含**：curl、rsync、ssh 客户端 - **固定版本**：Bun 1.3，确保 CI 环境可复现 因此 CI 中不能使用 `curl`、`rsync`、`ssh` 等命令，需用 `bun`/`cp`/`mv` 替代。 #### 3. github_mirror 配置 Runner 已配置 `github_mirror: 'https://gitea.com'`，从 gitea.com 镜像拉取 GitHub Actions（如 `actions/checkout`），解决国内无法访问 GitHub 的问题。如果 Action 拉取失败： ```bash # 清除缓存的 action（修复损坏的缓存） rm -rf /root/.cache/act/ systemctl restart act-runner ``` ### Pipeline 流程 ``` 推送代码到 Gitea (main 分支) │ ▼ ┌───────────────┐ │ quality │ ← Lint + 类型检查 │ (自动触发) │ └───────┬───────┘ │ ▼ ┌───────────────┐ │ build │ ← bun run build → dist/ │ (自动触发) │ └───────┬───────┘ │ ▼ ┌───────────────┐ │ deploy │ ← 原子替换 dist/ 目录 │ (手动触发) │ └───────────────┘ ``` ### Gitea Actions 配置 创建 `.gitea/workflows/deploy.yml`： ```yaml name: Build & Deploy Admin on: push: branches: [main] jobs: deploy: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v4 - name: Install dependencies run: bun install --frozen-lockfile - name: Lint & Type check run: | bun run lint bun run typecheck - name: Build run: bun run build env: VITE_API_BASE_URL: "" - name: Deploy to server run: | # 原子替换：通过 volume 挂载直接操作宿主机目录 mkdir -p /opt/duoqi-admin/dist-new cp -r dist/* /opt/duoqi-admin/dist-new/ # 备份当前版本 + 切换（mv 在同一文件系统上是原子操作） mv /opt/duoqi-admin/dist /opt/duoqi-admin/dist-old || true mv /opt/duoqi-admin/dist-new /opt/duoqi-admin/dist rm -rf /opt/duoqi-admin/dist-old ``` > **原子替换说明**：直接 `rm -rf dist && cp` 在中间有个时间窗口，用户会看到 404 或不完整文件。用 `dist-new → mv swap → rm old` 三步替换，`mv` 是原子操作（同一文件系统），切换瞬间完成，零停机。 > > **与 duoqi-api 的区别**：duoqi-api 通过 Docker 容器部署，CI 中需要 `docker build`/`docker compose`。duoqi-admin 是纯静态文件，CI 中只需 `cp` + `mv` 操作，更轻量。 --- ## 部署验证 ### 构建验证 ```bash # 本地构建 bun run build # 本地预览构建产物 bun run preview ``` ### 线上验证 ```bash # 检查首页可访问 curl -I https://admin.duoqi.me # 检查静态资源缓存头 curl -I https://admin.duoqi.me/assets/ # 功能验证（浏览器） # 1. 打开 https://admin.duoqi.me # 2. 登录 # 3. 执行 CRUD 操作 # 4. 验证 API 连通（浏览器 DevTools → Network） ``` --- ## API 代理方案对比 | 方案 | 优点 | 缺点 | |------|------|------| | **Nginx 代理（推荐）** | 无跨域问题、Cookie 共享、CDN 友好 | Nginx 配置多几行 | | 前端直连 api.duoqi.me | 简单 | 需要后端配 CORS、浏览器发跨域预检请求 | --- ## 服务器端目录结构 ``` /opt/ ├── gitea/ # Gitea（已有） ├── duoqi-api/ # API 部署（已有） │ ├── docker-compose.yml │ ├── .env.prod / .env.test │ └── repo/ ├── duoqi-admin/ # ← 新增 │ ├── dist/ # 当前线上版本 │ ├── dist-new/ # (部署时临时存在) │ └── dist-old/ # (部署后临时存在，自动清理) ├── backups/ # 备份（已有） └── scripts/ # 运维脚本（已有） ``` --- ## 运维管理 ### 手动部署（首次或紧急） ```bash # SSH 登录服务器 ssh root@your-server-ip # 拉取最新代码 cd /opt/duoqi-admin/repo && git pull origin main # 构建 bun install --frozen-lockfile bun run build # 原子替换 mkdir -p /opt/duoqi-admin/dist-new cp -r dist/* /opt/duoqi-admin/dist-new/ mv /opt/duoqi-admin/dist /opt/duoqi-admin/dist-old mv /opt/duoqi-admin/dist-new /opt/duoqi-admin/dist rm -rf /opt/duoqi-admin/dist-old ``` ### 回滚 ```bash # 保留最近一个版本的备份 # 回滚 = 将 dist-old 恢复 mv /opt/duoqi-admin/dist /opt/duoqi-admin/dist-failed mv /opt/duoqi-admin/dist-old /opt/duoqi-admin/dist rm -rf /opt/duoqi-admin/dist-failed ``` ### 日常检查 ```bash # 检查 Nginx 状态 systemctl status nginx # 检查站点响应 curl -s -o /dev/null -w "%{http_code}" https://admin.duoqi.me # 检查磁盘占用 du -sh /opt/duoqi-admin/dist/ ``` --- ## 故障排查 ### CI Action 拉取失败 **症状**：`actions/checkout` 或 `oven-sh/setup-bun` 拉取超时或 404。 ```bash # 检查 github_mirror 配置 grep github_mirror /opt/act-runner/config.yaml # 应输出：github_mirror: 'https://gitea.com' # 清除缓存的 action（修复损坏的缓存） rm -rf /root/.cache/act/ systemctl restart act-runner ``` ### CI checkout 失败（ECONNREFUSED） **症状**：job 容器无法连接 Gitea API。 ```bash # 检查容器网络配置 grep -A2 "network:" /opt/act-runner/config.yaml # 应包含：network: "host" # 确认 Gitea API 可达 curl http://localhost:3200/api/v1/repos/search?q=duoqi-admin ``` ### CI deploy 步骤找不到 /opt/duoqi-admin **症状**：`cp` 或 `mv` 报 No such file or directory。 ```bash # 检查 Runner 容器的 volume 挂载配置 grep "options:" /opt/act-runner/config.yaml # 应包含：-v /opt/duoqi-admin:/opt/duoqi-admin grep "valid_volumes:" -A3 /opt/act-runner/config.yaml # 应包含：- /opt/duoqi-admin ``` ### 白屏但 HTTP 200 **原因**：JS 加载失败或路由未回退。 ```bash # 检查 Nginx try_files 配置 nginx -T | grep try_files # 检查 dist/ 文件完整性 ls -la /opt/duoqi-admin/dist/ ls -la /opt/duoqi-admin/dist/assets/ ``` ### API 请求 404 **原因**：`/admin/` 代理未生效。 ```bash # 检查 Nginx 代理配置 nginx -T | grep -A5 "location /admin/" # 直接测试后端 curl http://localhost:3000/health ``` ### 样式/JS 未更新 **原因**：浏览器缓存。Vite 构建会自动给文件加 hash，但如果 HTML 被缓存则不会加载新资源。 ```bash # 检查 index.html 的 Cache-Control curl -I https://admin.duoqi.me/index.html # 应该没有长缓存头（index.html 不缓存，由 try_files 默认处理） ``` ### HTTPS 证书问题 ```bash # 检查证书覆盖的域名 echo | openssl s_client -connect admin.duoqi.me:443 2>/dev/null | openssl x509 -noout -text | grep DNS # 重新申请 sudo certbot --nginx --expand \ -d api.duoqi.me -d test-api.duoqi.me -d git.duoqi.me -d admin.duoqi.me ``` --- **文档版本**: v1.1.0 **最后更新**: 2026-04-22 **维护者**: Duoqi Team