PolyHermes/docs/DEPLOYMENT.md

PolyHermes 部署文档

本文档介绍如何部署 PolyHermes 项目，包括后端和前端的不同部署方式。

目录

• 一体化部署（推荐）
  • 使用 Docker Hub 镜像
  • 使用外部 Nginx 反向代理
• 后端部署
  • Java 直接部署
  • Docker 部署
• 前端部署
• 环境配置
• 常见问题

一体化部署（推荐）

将前后端一起部署到一个 Docker 容器中，使用 Nginx 提供前端静态文件并代理后端 API。

前置要求

• Docker 20.10+
• Docker Compose 2.0+

部署步骤

1. 使用 Docker Hub 镜像（推荐，生产环境首选）

使用官方构建的 Docker 镜像，无需本地构建，快速部署。

方式 1：独立部署（无需 clone 代码，推荐生产环境）

适用于生产环境，无需下载项目代码，只需配置文件即可部署。

# 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 代码）

# 如果已经 clone 了代码
./deploy.sh --use-docker-hub

方式 3：修改现有 docker-compose.yml

# 1. 修改 docker-compose.yml
#    取消注释：image: wrbug/polyhermes:latest
#    注释掉 build 部分

# 2. 创建 .env 文件（见下方环境配置）

# 3. 启动服务
docker-compose up -d

优势：

• ✅ 无需本地构建，快速部署
• ✅ 无需 clone 代码，只需配置文件即可部署
• ✅ 使用官方构建的镜像，包含正确的版本号
• ✅ 支持多架构（amd64、arm64），自动选择匹配的架构
• ✅ 生产环境推荐方式

拉取特定版本：

# 修改 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. 本地构建部署（开发环境）

适用于开发环境或需要自定义构建的场景。

# 使用部署脚本
./deploy.sh

脚本会自动：

• 检查 Docker 环境
• 创建 .env 配置文件（如果不存在）
• 构建 Docker 镜像（包含前后端）
• 启动服务（应用 + MySQL）

注意：本地构建的版本号会显示为 dev。

3. 手动部署

# 创建 .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 容器

# 使用 docker-compose.prod.yml 部署
docker-compose -f docker-compose.prod.yml up -d

2. 配置外部 Nginx

# 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）

# 安装 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 容器的端口改为内部端口，不对外暴露：

# 在 docker-compose.prod.yml 中
ports:
  - "127.0.0.1:80:80"  # 只绑定到本地，不对外暴露

Nginx 配置说明：

• 配置文件位置：docs/nginx-reverse-proxy.conf
• 支持 HTTPS（SSL/TLS）
• 支持 WebSocket 代理
• 包含安全头设置
• 支持负载均衡（可配置多个后端）

详细配置示例请参考：Nginx 反向代理配置

后端部署

Java 直接部署

前置要求

• JDK 17+
• MySQL 8.0+
• Gradle 7.5+（或使用 Gradle Wrapper）

部署步骤

1. 构建应用

cd backend
./gradlew clean bootJar

构建产物位于 build/libs/polyhermes-backend-1.0.0.jar

2. 使用部署脚本（推荐）

# 构建并创建部署文件
./deploy.sh java

# 或仅构建
./deploy.sh build

脚本会自动：

• 检查 Java 环境
• 构建应用
• 创建部署目录和启动脚本
• 生成 systemd 服务文件（可选）

3. 手动启动

# 开发环境
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）

# 复制服务文件
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. 使用部署脚本（推荐）

cd backend
./deploy.sh docker

脚本会自动：

• 检查 Docker 环境
• 创建 .env 配置文件（如果不存在）
• 构建 Docker 镜像
• 启动服务

2. 手动部署

# 创建 .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. 仅构建镜像

docker build -t polyhermes-backend:latest .

4. 运行容器

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. 使用构建脚本（推荐）

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. 手动构建

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/ 目录。

部署方式

方式1：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;
    }
}

方式2：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（开发/测试）

# 安装 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+）
• 清理缓存后重新构建：

  # 前端
  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 或联系 Twitter。