From a2a42ebf2328a4e2496d29fa9f5aec8c8cfc1851 Mon Sep 17 00:00:00 2001 From: hailin Date: Wed, 11 Feb 2026 02:00:40 -0800 Subject: [PATCH] docs: Add deployment guide for admin-web (DEPLOY.md) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 完整的部署文档，涵盖: - 环境要求与项目结构 - 3 步快速部署流程 - deploy.sh 全部命令参考 (Docker + Nginx + SSL) - 自定义域名部署说明 - Docker 三阶段构建说明 - SSL 证书管理 (自动续期、手动续期、强制重申) - Nginx HTTPS 配置特性说明 - 常见问题排查 (端口占用、构建失败、SSL 失败、日志查看) Co-Authored-By: Claude Opus 4.6 --- frontend/admin-web/DEPLOY.md | 288 +++++++++++++++++++++++++++++++++++ 1 file changed, 288 insertions(+) create mode 100644 frontend/admin-web/DEPLOY.md diff --git a/frontend/admin-web/DEPLOY.md b/frontend/admin-web/DEPLOY.md new file mode 100644 index 0000000..2aeee0f --- /dev/null +++ b/frontend/admin-web/DEPLOY.md @@ -0,0 +1,288 @@ +# Genex Admin Web 部署指南 + +## 环境要求 + +| 依赖 | 最低版本 | 说明 | +|------|---------|------| +| Docker | 20.10+ | 容器运行环境 | +| Docker Compose | v2+ | 容器编排 | +| Nginx | 1.18+ | 反向代理 (SSL 部署时安装) | +| Certbot | 1.0+ | Let's Encrypt 证书管理 (SSL 部署时安装) | + +服务器系统: Ubuntu 20.04+ / Debian 11+ + +## 项目结构 + +``` +frontend/admin-web/ +├── deploy.sh # 一键部署脚本 +├── Dockerfile # 三阶段 Docker 构建 +├── docker-compose.yml # Docker Compose 编排 +├── nginx/ +│ └── admin.gogenex.com.conf # Nginx HTTPS 配置模板 +├── package.json # Next.js 15 + React 18 +├── next.config.ts # Next.js 配置 (standalone 输出) +├── tsconfig.json # TypeScript 配置 +└── src/ + └── app/ # Next.js App Router + ├── layout.tsx # 根布局 + ├── page.tsx # 首页 (重定向到 /dashboard) + ├── providers.tsx # 全局 Providers + ├── globals.css # 全局样式 + └── api/health/route.ts # 健康检查 API +``` + +## 快速部署 (3 步) + +```bash +# 1. 克隆代码并进入目录 +cd frontend/admin-web + +# 2. 启动 Docker 容器 +./deploy.sh start + +# 3. 安装 Nginx + SSL 证书 +sudo ./deploy.sh nginx install +``` + +部署完成后访问: https://admin.gogenex.com + +--- + +## 详细步骤 + +### 第一步: 启动 Docker 容器 + +```bash +./deploy.sh start +``` + +脚本会自动: +1. 检查 Docker 和 Docker Compose +2. 检测端口占用，停止旧服务 +3. 构建三阶段 Docker 镜像 (deps → builder → runner) +4. 启动容器并等待健康检查通过 + +启动后容器监听 `localhost:3000`，可通过以下方式验证: + +```bash +# 查看容器状态 +./deploy.sh status + +# 验证健康检查 +curl http://localhost:3000/api/health +# 返回: {"status":"ok","service":"genex-admin-web","timestamp":"..."} +``` + +### 第二步: 配置域名 DNS + +在域名 DNS 管理中添加 A 记录: + +``` +admin.gogenex.com → <服务器公网 IP> +``` + +确保: +- DNS 已生效 (可用 `dig admin.gogenex.com` 验证) +- 服务器防火墙已放行 80 和 443 端口 + +### 第三步: 安装 Nginx + SSL 证书 + +```bash +sudo ./deploy.sh nginx install +``` + +脚本自动执行 5 个步骤: + +| 步骤 | 操作 | 说明 | +|------|------|------| +| 1/5 | 安装依赖 | 自动安装 nginx 和 certbot (如未安装) | +| 2/5 | HTTP 临时配置 | 部署 HTTP 站点，包含 ACME 验证路径 | +| 3/5 | 申请 SSL 证书 | certbot webroot 方式申请 Let's Encrypt 证书 | +| 4/5 | HTTPS 配置 | 部署完整 HTTPS 配置 (从 `nginx/` 目录读取) | +| 5/5 | 自动续期 | 配置 certbot renew hook，证书续期后自动重载 Nginx | + +过程中会提示确认 DNS 是否已生效，输入 `y` 继续。 + +--- + +## deploy.sh 命令参考 + +### Docker 命令 + +```bash +./deploy.sh build # 仅构建 Docker 镜像 (不启动) +./deploy.sh start # 构建并启动服务 (默认命令) +./deploy.sh stop # 停止服务 +./deploy.sh restart # 重启服务 (stop + start) +./deploy.sh logs # 查看实时日志 (Ctrl+C 退出) +./deploy.sh status # 查看容器状态 +./deploy.sh clean # 清理容器、镜像和卷 +``` + +### Nginx + SSL 命令 + +```bash +# 一键安装 Nginx + SSL (需要 root) +sudo ./deploy.sh nginx install [域名] [邮箱] + +# 仅申请/续期 SSL 证书 +sudo ./deploy.sh nginx ssl [域名] [邮箱] + +# 查看 Nginx 和证书状态 +./deploy.sh nginx status + +# 重载 Nginx 配置 +sudo ./deploy.sh nginx reload +``` + +默认域名: `admin.gogenex.com`，默认邮箱: `admin@gogenex.com` + +### 自定义域名部署 + +如果需要使用其他域名: + +```bash +# 1. 复制并修改 Nginx 配置模板 +cp nginx/admin.gogenex.com.conf nginx/myapp.example.com.conf +# 编辑文件，替换所有 admin.gogenex.com 为新域名 + +# 2. 使用自定义域名安装 +sudo ./deploy.sh nginx install myapp.example.com admin@example.com +``` + +### 环境变量 + +```bash +# 修改服务端口 (默认 3000) +PORT=8080 ./deploy.sh start +``` + +--- + +## Docker 构建说明 + +采用三阶段构建优化镜像大小: + +``` +阶段 1 (deps) - node:20-alpine - 安装 npm 依赖 +阶段 2 (builder) - node:20-alpine - 执行 next build +阶段 3 (runner) - node:20-alpine - 仅复制 standalone 产物运行 +``` + +关键配置: +- `next.config.ts` 中 `output: 'standalone'` 启用独立输出模式 +- 运行时使用非 root 用户 `nextjs:nodejs` (UID/GID 1001) +- 内置 curl 用于 Docker 健康检查 + +--- + +## SSL 证书管理 + +### 证书位置 + +``` +/etc/letsencrypt/live/admin.gogenex.com/ +├── fullchain.pem # 完整证书链 +├── privkey.pem # 私钥 +├── cert.pem # 服务器证书 +└── chain.pem # 中间证书 +``` + +### 自动续期 + +certbot 安装后自动配置 systemd timer，每天检查证书有效期。 +证书到期前 30 天自动续期，续期后通过 renew hook 自动重载 Nginx。 + +```bash +# 查看续期定时器状态 +systemctl status certbot.timer + +# 手动测试续期 (不实际续期) +sudo certbot renew --dry-run + +# 手动续期 +sudo certbot renew +``` + +### 强制重新申请 + +```bash +sudo certbot certonly --force-renewal \ + --webroot --webroot-path=/var/www/certbot \ + -d admin.gogenex.com +sudo systemctl reload nginx +``` + +--- + +## Nginx 配置说明 + +HTTPS 配置 (`nginx/admin.gogenex.com.conf`) 包含: + +| 特性 | 说明 | +|------|------| +| HTTP → HTTPS 重定向 | 所有 80 端口请求 301 跳转到 443 | +| TLS 1.2 / 1.3 | 现代加密协议，禁用旧版本 | +| HSTS | `max-age=63072000` (2年)，强制浏览器使用 HTTPS | +| Gzip 压缩 | 压缩 JS/CSS/JSON 等文本资源 | +| 安全响应头 | X-Frame-Options, X-Content-Type-Options, X-XSS-Protection | +| 静态资源长缓存 | `/_next/static/` 缓存 1 年 (文件名含 hash) | +| WebSocket 支持 | 支持 Next.js HMR 和实时功能 | +| 反向代理 | 转发到 `127.0.0.1:3000` (Docker 容器) | + +--- + +## 常见问题 + +### 端口被占用 + +```bash +# 查看 3000 端口占用 +lsof -i :3000 +# 或 +ss -tlnp | grep 3000 + +# deploy.sh start 会自动检测并停止旧服务 +``` + +### Docker 构建失败 + +```bash +# 清理缓存重新构建 +./deploy.sh clean +./deploy.sh start + +# 查看构建日志 +docker compose build --no-cache 2>&1 | tee build.log +``` + +### SSL 证书申请失败 + +常见原因: +1. DNS 未生效 - 用 `dig admin.gogenex.com` 检查 A 记录 +2. 80 端口未放行 - 用 `sudo ufw allow 80` 放行 +3. 防火墙/安全组拦截 - 检查云服务商安全组规则 + +```bash +# 手动测试 ACME 验证路径 +echo "test" > /var/www/certbot/.well-known/acme-challenge/test +curl http://admin.gogenex.com/.well-known/acme-challenge/test +# 应返回 "test" +``` + +### 查看日志 + +```bash +# Docker 容器日志 +./deploy.sh logs + +# Nginx 访问日志 +tail -f /var/log/nginx/admin.gogenex.com.access.log + +# Nginx 错误日志 +tail -f /var/log/nginx/admin.gogenex.com.error.log + +# Certbot 日志 +tail -f /var/log/letsencrypt/letsencrypt.log +```