Files
PolyHermes/docs/DEPLOYMENT.md
T
WrBug 7d752073fb feat: 添加安全检查和部署优化
- 添加 JWT_SECRET 和 ADMIN_RESET_PASSWORD_KEY 安全检查,防止使用默认值
- 创建 docker-compose.prod.yml 和 docker-compose.prod.env.example,支持独立部署
- 添加 Nginx 反向代理配置示例,支持 HTTPS 和域名绑定
- 更新部署文档,将 Docker Hub 部署方式放在首位
- 添加多架构构建支持(amd64、arm64)
- 优化部署文档结构,提供更清晰的部署指南
2025-12-07 17:08:56 +08:00

651 lines
15 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# PolyHermes 部署文档
本文档介绍如何部署 PolyHermes 项目,包括后端和前端的不同部署方式。
## 目录
- [一体化部署(推荐)](#一体化部署推荐)
- [使用 Docker Hub 镜像](#使用-docker-hub-镜像推荐生产环境首选)
- [使用外部 Nginx 反向代理](#使用外部-nginx-反向代理生产环境推荐)
- [后端部署](#后端部署)
- [Java 直接部署](#java-直接部署)
- [Docker 部署](#docker-部署)
- [前端部署](#前端部署)
- [环境配置](#环境配置)
- [常见问题](#常见问题)
## 一体化部署(推荐)
将前后端一起部署到一个 Docker 容器中,使用 Nginx 提供前端静态文件并代理后端 API。
### 前置要求
- Docker 20.10+
- Docker Compose 2.0+
### 部署步骤
1. **使用 Docker Hub 镜像(推荐,生产环境首选)**
使用官方构建的 Docker 镜像,无需本地构建,快速部署。
**方式 1:独立部署(无需 clone 代码,推荐生产环境)**
适用于生产环境,无需下载项目代码,只需配置文件即可部署。
```bash
# 1. 创建部署目录
mkdir polyhermes && cd polyhermes
# 2. 下载生产环境配置文件
# 从 GitHub 下载 docker-compose.prod.yml 和 docker-compose.prod.env.example
curl -O https://raw.githubusercontent.com/WrBug/PolyHermes/main/docker-compose.prod.yml
curl -O https://raw.githubusercontent.com/WrBug/PolyHermes/main/docker-compose.prod.env.example
# 3. 创建配置文件
cp docker-compose.prod.env.example .env
# 4. 编辑 .env 文件,修改以下必需配置:
# - DB_PASSWORD: 数据库密码(建议使用强密码)
# - JWT_SECRET: JWT 密钥(使用 openssl rand -hex 64 生成)
# - ADMIN_RESET_PASSWORD_KEY: 管理员密码重置密钥(使用 openssl rand -hex 32 生成)
#
# 生成随机密钥示例:
# openssl rand -hex 64 # 用于 JWT_SECRET
# openssl rand -hex 32 # 用于 ADMIN_RESET_PASSWORD_KEY
# 5. 启动服务
docker-compose -f docker-compose.prod.yml up -d
# 6. 查看日志
docker-compose -f docker-compose.prod.yml logs -f
# 7. 停止服务
docker-compose -f docker-compose.prod.yml down
```
**方式 2:使用部署脚本(需要 clone 代码)**
```bash
# 如果已经 clone 了代码
./deploy.sh --use-docker-hub
```
**方式 3:修改现有 docker-compose.yml**
```bash
# 1. 修改 docker-compose.yml
# 取消注释:image: wrbug/polyhermes:latest
# 注释掉 build 部分
# 2. 创建 .env 文件(见下方环境配置)
# 3. 启动服务
docker-compose up -d
```
**优势**
- ✅ 无需本地构建,快速部署
- ✅ 无需 clone 代码,只需配置文件即可部署
- ✅ 使用官方构建的镜像,包含正确的版本号
- ✅ 支持多架构(amd64、arm64),自动选择匹配的架构
- ✅ 生产环境推荐方式
**拉取特定版本**
```bash
# 修改 docker-compose.prod.yml 中的镜像标签
# image: wrbug/polyhermes:v1.0.0
# 或使用环境变量
export IMAGE_TAG=v1.0.0
# 在 docker-compose.prod.yml 中使用: image: wrbug/polyhermes:${IMAGE_TAG:-latest}
```
2. **本地构建部署(开发环境)**
适用于开发环境或需要自定义构建的场景。
```bash
# 使用部署脚本
./deploy.sh
```
脚本会自动:
- 检查 Docker 环境
- 创建 `.env` 配置文件(如果不存在)
- 构建 Docker 镜像(包含前后端)
- 启动服务(应用 + MySQL
**注意**:本地构建的版本号会显示为 `dev`
3. **手动部署**
```bash
# 创建 .env 文件
cat > .env <<EOF
DB_URL=jdbc:mysql://mysql:3306/polyhermes?useSSL=false&serverTimezone=UTC&characterEncoding=utf8&allowPublicKeyRetrieval=true
DB_USERNAME=root
DB_PASSWORD=your_password_here
SPRING_PROFILES_ACTIVE=prod
SERVER_PORT=80
POLYGON_RPC_URL=https://polygon-rpc.com
JWT_SECRET=your-jwt-secret-key-change-in-production
ADMIN_RESET_PASSWORD_KEY=your-admin-reset-key-change-in-production
EOF
# 构建并启动
docker-compose build
docker-compose up -d
# 查看日志
docker-compose logs -f
# 停止服务
docker-compose down
```
4. **访问应用**
- 前端和后端统一访问:`http://localhost:80`
- Nginx 自动处理:
- `/api/*` → 后端 API`localhost:8000`
- `/ws` → 后端 WebSocket`localhost:8000`
- 其他路径 → 前端静态文件
### 架构说明
```
用户请求
Nginx (端口 80)
├─ /api/* → 后端服务 (localhost:8000)
├─ /ws → 后端 WebSocket (localhost:8000)
└─ /* → 前端静态文件 (/usr/share/nginx/html)
```
### 优势
- ✅ 单一容器,简化部署
- ✅ 统一端口,无需配置 CORS
- ✅ 自动处理前后端路由
- ✅ 生产环境就绪
### 使用外部 Nginx 反向代理(生产环境推荐)
在生产环境中,建议在 Docker 容器外部部署 Nginx 作为反向代理,用于:
- **SSL/TLS 终止**:处理 HTTPS 请求
- **域名绑定**:绑定自定义域名
- **负载均衡**:支持多个后端实例
- **更灵活的配置**:更细粒度的控制
**部署架构**
```
用户请求 (HTTPS)
外部 Nginx (443) - SSL 终止
Docker 容器 (80) - 内部 Nginx + 后端
├─ /api/* → 后端服务 (localhost:8000)
├─ /ws → 后端 WebSocket (localhost:8000)
└─ /* → 前端静态文件
```
**部署步骤**
1. **部署 Docker 容器**
```bash
# 使用 docker-compose.prod.yml 部署
docker-compose -f docker-compose.prod.yml up -d
```
2. **配置外部 Nginx**
```bash
# 1. 下载 Nginx 配置示例
curl -O https://raw.githubusercontent.com/WrBug/PolyHermes/main/docs/nginx-reverse-proxy.conf
# 2. 复制到 Nginx 配置目录
sudo cp nginx-reverse-proxy.conf /etc/nginx/sites-available/polyhermes
# 3. 编辑配置文件,修改域名和 SSL 证书路径
sudo nano /etc/nginx/sites-available/polyhermes
# 修改以下内容:
# - server_name: 改为你的域名
# - ssl_certificate: SSL 证书路径
# - ssl_certificate_key: SSL 私钥路径
# - upstream server: 如果 Docker 容器端口不是 80,需要修改
# 4. 创建软链接
sudo ln -s /etc/nginx/sites-available/polyhermes /etc/nginx/sites-enabled/
# 5. 测试配置
sudo nginx -t
# 6. 重载配置
sudo systemctl reload nginx
```
3. **配置 SSL 证书(使用 Let's Encrypt**
```bash
# 安装 Certbot
sudo apt-get update
sudo apt-get install certbot python3-certbot-nginx
# 获取 SSL 证书
sudo certbot --nginx -d your-domain.com -d www.your-domain.com
# 证书会自动配置到 Nginx,并设置自动续期
```
4. **修改 Docker 端口映射(可选)**
如果使用外部 Nginx,可以将 Docker 容器的端口改为内部端口,不对外暴露:
```yaml
# 在 docker-compose.prod.yml 中
ports:
- "127.0.0.1:80:80" # 只绑定到本地,不对外暴露
```
**Nginx 配置说明**
- 配置文件位置:`docs/nginx-reverse-proxy.conf`
- 支持 HTTPSSSL/TLS
- 支持 WebSocket 代理
- 包含安全头设置
- 支持负载均衡(可配置多个后端)
详细配置示例请参考:[Nginx 反向代理配置](nginx-reverse-proxy.conf)
## 后端部署
### Java 直接部署
#### 前置要求
- JDK 17+
- MySQL 8.0+
- Gradle 7.5+(或使用 Gradle Wrapper
#### 部署步骤
1. **构建应用**
```bash
cd backend
./gradlew clean bootJar
```
构建产物位于 `build/libs/polyhermes-backend-1.0.0.jar`
2. **使用部署脚本(推荐)**
```bash
# 构建并创建部署文件
./deploy.sh java
# 或仅构建
./deploy.sh build
```
脚本会自动:
- 检查 Java 环境
- 构建应用
- 创建部署目录和启动脚本
- 生成 systemd 服务文件(可选)
3. **手动启动**
```bash
# 开发环境
java -jar build/libs/polyhermes-backend-1.0.0.jar --spring.profiles.active=dev
# 生产环境
java -jar build/libs/polyhermes-backend-1.0.0.jar --spring.profiles.active=prod
```
4. **使用 systemd 管理(Linux**
```bash
# 复制服务文件
sudo cp deploy/polyhermes-backend.service /etc/systemd/system/
# 编辑服务文件,修改路径和用户
sudo nano /etc/systemd/system/polyhermes-backend.service
# 启动服务
sudo systemctl daemon-reload
sudo systemctl enable polyhermes-backend
sudo systemctl start polyhermes-backend
# 查看日志
sudo journalctl -u polyhermes-backend -f
```
### Docker 部署
#### 前置要求
- Docker 20.10+
- Docker Compose 2.0+
#### 部署步骤
1. **使用部署脚本(推荐)**
```bash
cd backend
./deploy.sh docker
```
脚本会自动:
- 检查 Docker 环境
- 创建 `.env` 配置文件(如果不存在)
- 构建 Docker 镜像
- 启动服务
2. **手动部署**
```bash
# 创建 .env 文件
cat > .env <<EOF
DB_URL=jdbc:mysql://mysql:3306/polyhermes?useSSL=false&serverTimezone=UTC&characterEncoding=utf8&allowPublicKeyRetrieval=true
DB_USERNAME=root
DB_PASSWORD=your_password_here
SPRING_PROFILES_ACTIVE=prod
SERVER_PORT=8000
POLYGON_RPC_URL=https://polygon-rpc.com
JWT_SECRET=your-jwt-secret-key-change-in-production
ADMIN_RESET_PASSWORD_KEY=your-admin-reset-key-change-in-production
EOF
# 构建并启动
docker-compose up -d
# 查看日志
docker-compose logs -f
# 停止服务
docker-compose down
```
3. **仅构建镜像**
```bash
docker build -t polyhermes-backend:latest .
```
4. **运行容器**
```bash
docker run -d \
--name polyhermes-backend \
-p 8000:8000 \
-e SPRING_PROFILES_ACTIVE=prod \
-e DB_URL=jdbc:mysql://host.docker.internal:3306/polyhermes?useSSL=false&allowPublicKeyRetrieval=true \
-e DB_USERNAME=root \
-e DB_PASSWORD=your_password \
-e JWT_SECRET=your-jwt-secret \
polyhermes-backend:latest
```
## 前端部署
### 构建步骤
1. **使用构建脚本(推荐)**
```bash
cd frontend
# 使用默认后端地址(http://127.0.0.1:8000
./build.sh
# 或指定自定义后端地址
./build.sh --api-url http://your-backend-server.com:8000
# 或使用环境变量
VITE_API_URL=http://your-backend-server.com:8000 ./build.sh
```
2. **手动构建**
```bash
cd frontend
# 创建环境配置文件
cat > .env.production <<EOF
VITE_API_URL=http://your-backend-server.com:8000
VITE_WS_URL=ws://your-backend-server.com:8000
EOF
# 安装依赖(首次)
npm install
# 构建
npm run build
```
构建产物位于 `dist/` 目录。
### 部署方式
#### 方式1Nginx 部署
```nginx
server {
listen 80;
server_name your-domain.com;
root /path/to/frontend/dist;
index index.html;
# API 代理
location /api {
proxy_pass http://localhost:8000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
# WebSocket 代理
location /ws {
proxy_pass http://localhost:8000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
}
# 前端路由(SPA
location / {
try_files $uri $uri/ /index.html;
}
}
```
#### 方式2Apache 部署
```apache
<VirtualHost *:80>
ServerName your-domain.com
DocumentRoot /path/to/frontend/dist
# API 代理
ProxyPass /api http://localhost:8000/api
ProxyPassReverse /api http://localhost:8000/api
# WebSocket 代理
ProxyPass /ws ws://localhost:8000/ws
ProxyPassReverse /ws ws://localhost:8000/ws
# 前端路由(SPA
<Directory /path/to/frontend/dist>
Options Indexes FollowSymLinks
AllowOverride All
Require all granted
RewriteEngine On
RewriteBase /
RewriteRule ^index\.html$ - [L]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . /index.html [L]
</Directory>
</VirtualHost>
```
#### 方式3:使用 serve(开发/测试)
```bash
# 安装 serve
npm install -g serve
# 启动服务
serve -s dist -l 3000
```
## 环境配置
### 后端环境变量
| 变量名 | 说明 | 默认值 | 必需 |
|--------|------|--------|------|
| `SPRING_PROFILES_ACTIVE` | Spring Profile | `dev` | 否 |
| `DB_URL` | 数据库连接 URL | - | 是(生产) |
| `DB_USERNAME` | 数据库用户名 | `root` | 是(生产) |
| `DB_PASSWORD` | 数据库密码 | - | 是(生产) |
| `SERVER_PORT` | 服务器端口 | `8000` | 否 |
| `POLYGON_RPC_URL` | Polygon RPC 地址 | `https://polygon-rpc.com` | 否 |
| `JWT_SECRET` | JWT 密钥 | - | 是(生产) |
| `ADMIN_RESET_PASSWORD_KEY` | 管理员密码重置密钥 | - | 是(生产) |
### 前端环境变量
| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `VITE_API_URL` | 后端 API 地址 | `http://127.0.0.1:8000` |
| `VITE_WS_URL` | WebSocket 地址 | `ws://127.0.0.1:8000` |
### 配置文件说明
#### 后端配置文件
- `application.properties` - 基础配置(所有环境共享)
- `application-dev.properties` - 开发环境配置
- `application-prod.properties` - 生产环境配置
通过 `--spring.profiles.active=prod` 或环境变量 `SPRING_PROFILES_ACTIVE=prod` 切换环境。
#### 前端环境变量
Vite 使用 `.env.production` 文件在构建时注入环境变量。构建脚本会自动创建此文件。
## 常见问题
### 1. 数据库连接失败
**问题**: 后端无法连接数据库
**解决方案**:
- 检查数据库服务是否运行
- 检查数据库连接 URL、用户名、密码是否正确
- 检查防火墙是否允许连接
- 对于 Docker 部署,确保使用正确的数据库地址(`mysql` 而非 `localhost`
### 2. 前端无法连接后端
**问题**: 前端请求后端 API 失败
**解决方案**:
- 检查后端服务是否运行
- 检查 `VITE_API_URL` 配置是否正确
- 检查 CORS 配置(如果跨域)
- 检查网络连接和防火墙
### 3. WebSocket 连接失败
**问题**: WebSocket 无法建立连接
**解决方案**:
- 检查 `VITE_WS_URL` 配置是否正确
- 检查 WebSocket 代理配置(Nginx/Apache
- 检查防火墙是否允许 WebSocket 连接
- 检查后端 WebSocket 服务是否正常
### 4. Docker 容器无法访问数据库
**问题**: Docker 容器中的后端无法连接宿主机数据库
**解决方案**:
- 使用 `host.docker.internal` 作为数据库地址(Mac/Windows
- 使用 Docker 网络连接(推荐使用 docker-compose
- 检查数据库是否允许远程连接
### 5. 构建失败
**问题**: 前端或后端构建失败
**解决方案**:
- 检查 Node.js 版本(需要 18+
- 检查 Java 版本(需要 17+)
- 清理缓存后重新构建:
```bash
# 前端
rm -rf node_modules dist
npm install
npm run build
# 后端
./gradlew clean build
```
## 生产环境检查清单
- [ ] 修改所有默认密码和密钥(JWT_SECRET、ADMIN_RESET_PASSWORD_KEY、数据库密码)
- [ ] 配置正确的数据库连接(使用 SSL)
- [ ] 设置正确的 Spring Profile`prod`
- [ ] 配置正确的后端 API 地址(前端)
- [ ] 配置反向代理(Nginx/Apache
- [ ] 配置 HTTPS(生产环境推荐)
- [ ] 配置防火墙规则
- [ ] 设置日志轮转
- [ ] 配置监控和告警
- [ ] 定期备份数据库
## 性能优化建议
### 后端
- 调整 JVM 参数(堆内存、GC 策略)
- 配置数据库连接池大小
- 启用 HTTP 压缩
- 配置缓存策略
### 前端
- 启用 Gzip 压缩(Nginx
- 配置静态资源缓存
- 使用 CDN 加速
- 启用 HTTP/2
## 安全建议
- 使用 HTTPS(生产环境必须)
- 配置 CORS 白名单
- 定期更新依赖包
- 使用强密码和密钥
- 限制数据库访问权限
- 配置防火墙规则
- 定期备份数据
- 监控异常访问
## 技术支持
如有问题,请提交 Issue 到 [GitHub](https://github.com/WrBug/PolyHermes) 或联系 [Twitter](https://x.com/quant_tr)。