docs: 清理根目录临时文档
- 删除过时的版本发布说明（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>
This commit is contained in:
WrBug
@@ -0,0 +1,335 @@
|
||||
# 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 并附上日志输出
|
||||
|
||||
---
|
||||
|
||||
**祝部署顺利！** 🎉
|
||||
Reference in New Issue
Block a user