PolyHermes/docs/zh/DEPLOYMENT_GUIDE.md

PolyHermes 一键部署指南

本文档介绍如何使用交互式一键部署脚本快速部署 PolyHermes 应用。

📋 前置要求

必需软件

• Docker: 版本 20.10 或更高
• Docker Compose: 版本 2.0 或更高（或 docker-compose v1.29+）

环境准备

# macOS 安装 Docker
brew install docker

# Ubuntu/Debian 安装 Docker
curl -fsSL https://get.docker.com | sh

# CentOS/RHEL 安装 Docker  
yum install docker-ce docker-ce-cli containerd.io

🚀 快速开始

1. 克隆项目（如果尚未克隆）

git clone https://github.com/WrBug/PolyHermes.git
cd PolyHermes

2. 运行部署脚本

./deploy-interactive.sh

3. 按提示配置

脚本会引导你完成以下配置：

基础配置

• 服务器端口：应用对外暴露的端口（默认：80）
• MySQL 端口：数据库外部访问端口（默认：3307，避免与本地 MySQL 冲突）
• 时区：服务器时区（默认：Asia/Shanghai）

数据库配置

• 数据库用户名：默认为 root
• 数据库密码：回车自动生成 32 字符随机密码

安全配置（关键）

• JWT 密钥：回车自动生成 128 字符随机密钥
• 管理员密码重置密钥：回车自动生成 64 字符随机密钥
• 加密密钥：用于加密 API Key，回车自动生成 64 字符随机密钥

日志配置

• Root 日志级别：第三方库日志级别（默认：WARN）
  • 可选：TRACE, DEBUG, INFO, WARN, ERROR, OFF
• 应用日志级别：应用代码日志级别（默认：INFO）

其他配置

• Spring Profile：环境配置（默认：prod）
• 允许预发布版本：是否允许自动更新到预发布版本（默认：false）
• GitHub 仓库：项目仓库地址（默认：WrBug/PolyHermes）

4. 确认并部署

配置完成后，脚本会：

1. 生成 .env 配置文件
2. 显示配置摘要
3. 请求确认部署
4. 拉取 Docker Hub 镜像
5. 启动服务
6. 执行健康检查

📝 配置示例

使用默认值部署（推荐）

所有配置项直接回车，脚本会自动生成安全的随机密钥：

服务器端口 [默认: 80]: ⏎
MySQL 端口（外部访问） [默认: 3307]: ⏎
时区 [默认: Asia/Shanghai]: ⏎
数据库用户名 [默认: root]: ⏎
数据库密码 [回车自动生成]: ⏎
JWT 密钥 [回车自动生成]: ⏎
管理员密码重置密钥 [回车自动生成]: ⏎
加密密钥（用于加密 API Key） [回车自动生成]: ⏎
Root 日志级别（第三方库） [默认: WARN]: ⏎
应用日志级别 [默认: INFO]: ⏎
Spring Profile [默认: prod]: ⏎
允许预发布版本更新 [默认: false]: ⏎
GitHub 仓库 [默认: WrBug/PolyHermes]: ⏎

自定义端口部署

如果需要使用不同的端口：

服务器端口 [默认: 80]: 8080⏎
MySQL 端口（外部访问） [默认: 3307]: 33306⏎

开发环境部署

启用 DEBUG 日志：

Root 日志级别（第三方库） [默认: WARN]: DEBUG⏎
应用日志级别 [默认: INFO]: DEBUG⏎

🔧 部署后管理

访问应用

部署完成后，访问：

http://localhost:80

（或你配置的自定义端口）

常用命令

# 查看服务状态
docker compose -f docker-compose.prod.yml ps

# 查看实时日志
docker compose -f docker-compose.prod.yml logs -f

# 仅查看应用日志
docker compose -f docker-compose.prod.yml logs -f app

# 停止服务
docker compose -f docker-compose.prod.yml down

# 重启服务
docker compose -f docker-compose.prod.yml restart

# 更新到最新版本
docker pull wrbug/polyhermes:latest
docker compose -f docker-compose.prod.yml up -d

数据库连接

使用配置的凭据连接到 MySQL：

mysql -h 127.0.0.1 -P 3307 -u root -p
# 输入你在部署时设置的数据库密码

或使用图形化工具（如 DBeaver、Navicat）：

• 主机: localhost
• 端口: 3307（或你配置的端口）
• 数据库: polyhermes
• 用户名: root（或你配置的用户名）
• 密码: 部署时设置的密码（可在 .env 文件中查看）

🔐 安全最佳实践

保护配置文件

# 设置 .env 文件权限
chmod 600 .env

# 确保 .env 已添加到 .gitignore
echo ".env" >> .gitignore

定期更换密钥

生产环境建议定期更换安全密钥：

# 生成新的 JWT 密钥（128字符）
openssl rand -hex 64

# 生成新的管理员重置密钥（64字符）
openssl rand -hex 32

# 更新 .env 文件后重启服务
docker compose -f docker-compose.prod.yml restart

备份数据库

# 备份数据库
docker exec polyhermes-mysql mysqldump -u root -p polyhermes > backup_$(date +%Y%m%d).sql

# 恢复数据库
docker exec -i polyhermes-mysql mysql -u root -p polyhermes < backup_20260201.sql

🌐 生产环境部署建议

1. 使用反向代理

建议使用 Nginx 或 Caddy 作为反向代理：

# Nginx 配置示例
server {
    listen 443 ssl http2;
    server_name polyhermes.yourdomain.com;
    
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    location / {
        proxy_pass http://localhost:80;
        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;
    }
}

2. 配置防火墙

# UFW (Ubuntu)
ufw allow 80/tcp
ufw allow 443/tcp
ufw enable

# Firewalld (CentOS)
firewall-cmd --add-service=http --permanent
firewall-cmd --add-service=https --permanent
firewall-cmd --reload

3. 启用自动更新

配置定时任务自动检查并更新镜像：

# 创建更新脚本
cat > /opt/polyhermes-update.sh <<'EOF'
#!/bin/bash
cd /path/to/PolyHermes
docker pull wrbug/polyhermes:latest
docker compose -f docker-compose.prod.yml up -d
EOF

chmod +x /opt/polyhermes-update.sh

# 添加到 crontab（每天凌晨 3 点检查更新）
echo "0 3 * * * /opt/polyhermes-update.sh >> /var/log/polyhermes-update.log 2>&1" | crontab -

🐛 故障排查

服务无法启动

# 查看详细错误日志
docker compose -f docker-compose.prod.yml logs

# 检查容器状态
docker compose -f docker-compose.prod.yml ps

数据库连接失败

# 检查 MySQL 容器状态
docker logs polyhermes-mysql

# 测试数据库连接
docker exec polyhermes-mysql mysql -u root -p -e "SELECT 1"

端口被占用

# 查找占用端口的进程
lsof -i :80
# 或
netstat -tulpn | grep :80

# 修改 SERVER_PORT 环境变量
vim .env  # 修改 SERVER_PORT=8080
docker compose -f docker-compose.prod.yml up -d

镜像拉取失败

如果 Docker Hub 访问受限，可以配置镜像加速器：

# 配置 Docker 镜像加速器
sudo mkdir -p /etc/docker
sudo tee /etc/docker/daemon.json <<-'EOF'
{
  "registry-mirrors": [
    "https://docker.mirrors.ustc.edu.cn",
    "https://hub-mirror.c.163.com"
  ]
}
EOF

sudo systemctl restart docker

📚 更多资源

• 项目 README
• 发布日志
• GitHub 仓库
• 问题反馈

📞 获取帮助

如遇到问题，请：

1. 查看上方的故障排查章节
2. 检查 GitHub Issues
3. 提交新的 Issue 并附上日志输出

---

祝部署顺利！ 🎉