WrBug
01a1836659
- 删除过时的版本发布说明（RELEASE.md 和 RELEASE_NOTES_v2.0.*.md） - 删除临时检查报告（CHECK_AND_FIX_REPORT.md、IMPLEMENTATION_COMPLETE.md、MISSING_ITEMS_CHECK.md） - 所有版本发布信息统一在 RELEASE_NOTES.md 中管理 - 添加新的部署指南文档和 Docker 构建配置 Co-authored-by: Cursor <cursoragent@cursor.com>
336 lines
7.4 KiB
Markdown
336 lines
7.4 KiB
Markdown
# PolyHermes 一键部署指南
|
||
|
||
本文档介绍如何使用交互式一键部署脚本快速部署 PolyHermes 应用。
|
||
|
||
## 📋 前置要求
|
||
|
||
### 必需软件
|
||
|
||
- **Docker**: 版本 20.10 或更高
|
||
- **Docker Compose**: 版本 2.0 或更高（或 `docker-compose` v1.29+）
|
||
|
||
### 环境准备
|
||
|
||
```bash
|
||
# 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. 克隆项目（如果尚未克隆）
|
||
|
||
```bash
|
||
git clone https://github.com/WrBug/PolyHermes.git
|
||
cd PolyHermes
|
||
```
|
||
|
||
### 2. 运行部署脚本
|
||
|
||
```bash
|
||
./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
|
||
```
|
||
|
||
（或你配置的自定义端口）
|
||
|
||
### 常用命令
|
||
|
||
```bash
|
||
# 查看服务状态
|
||
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：
|
||
|
||
```bash
|
||
mysql -h 127.0.0.1 -P 3307 -u root -p
|
||
# 输入你在部署时设置的数据库密码
|
||
```
|
||
|
||
或使用图形化工具（如 DBeaver、Navicat）：
|
||
- **主机**: `localhost`
|
||
- **端口**: `3307`（或你配置的端口）
|
||
- **数据库**: `polyhermes`
|
||
- **用户名**: `root`（或你配置的用户名）
|
||
- **密码**: 部署时设置的密码（可在 `.env` 文件中查看）
|
||
|
||
## 🔐 安全最佳实践
|
||
|
||
### 保护配置文件
|
||
|
||
```bash
|
||
# 设置 .env 文件权限
|
||
chmod 600 .env
|
||
|
||
# 确保 .env 已添加到 .gitignore
|
||
echo ".env" >> .gitignore
|
||
```
|
||
|
||
### 定期更换密钥
|
||
|
||
生产环境建议定期更换安全密钥：
|
||
|
||
```bash
|
||
# 生成新的 JWT 密钥（128字符）
|
||
openssl rand -hex 64
|
||
|
||
# 生成新的管理员重置密钥（64字符）
|
||
openssl rand -hex 32
|
||
|
||
# 更新 .env 文件后重启服务
|
||
docker compose -f docker-compose.prod.yml restart
|
||
```
|
||
|
||
### 备份数据库
|
||
|
||
```bash
|
||
# 备份数据库
|
||
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
|
||
# 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. 配置防火墙
|
||
|
||
```bash
|
||
# 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. 启用自动更新
|
||
|
||
配置定时任务自动检查并更新镜像：
|
||
|
||
```bash
|
||
# 创建更新脚本
|
||
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 -
|
||
```
|
||
|
||
## 🐛 故障排查
|
||
|
||
### 服务无法启动
|
||
|
||
```bash
|
||
# 查看详细错误日志
|
||
docker compose -f docker-compose.prod.yml logs
|
||
|
||
# 检查容器状态
|
||
docker compose -f docker-compose.prod.yml ps
|
||
```
|
||
|
||
### 数据库连接失败
|
||
|
||
```bash
|
||
# 检查 MySQL 容器状态
|
||
docker logs polyhermes-mysql
|
||
|
||
# 测试数据库连接
|
||
docker exec polyhermes-mysql mysql -u root -p -e "SELECT 1"
|
||
```
|
||
|
||
### 端口被占用
|
||
|
||
```bash
|
||
# 查找占用端口的进程
|
||
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 访问受限，可以配置镜像加速器：
|
||
|
||
```bash
|
||
# 配置 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](../../README.md)
|
||
- [发布日志](../../RELEASE.md)
|
||
- [GitHub 仓库](https://github.com/WrBug/PolyHermes)
|
||
- [问题反馈](https://github.com/WrBug/PolyHermes/issues)
|
||
|
||
## 📞 获取帮助
|
||
|
||
如遇到问题，请：
|
||
|
||
1. 查看上方的**故障排查**章节
|
||
2. 检查 [GitHub Issues](https://github.com/WrBug/PolyHermes/issues)
|
||
3. 提交新的 Issue 并附上日志输出
|
||
|
||
---
|
||
|
||
**祝部署顺利！** 🎉
|