docs: Add deployment guide for admin-web (DEPLOY.md)
完整的部署文档，涵盖: - 环境要求与项目结构 - 3 步快速部署流程 - deploy.sh 全部命令参考 (Docker + Nginx + SSL) - 自定义域名部署说明 - Docker 三阶段构建说明 - SSL 证书管理 (自动续期、手动续期、强制重申) - Nginx HTTPS 配置特性说明 - 常见问题排查 (端口占用、构建失败、SSL 失败、日志查看) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
parent
51f4c60fe5
commit
a2a42ebf23
|
|
@ -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
|
||||
```
|
||||
Loading…
Reference in New Issue