From f71651fc7e7fc7ab1bf1e07bfed0f004abed2281 Mon Sep 17 00:00:00 2001 From: huangzhenpc Date: Thu, 15 Jan 2026 21:45:51 +0800 Subject: [PATCH] =?UTF-8?q?=E6=B7=BB=E5=8A=A0=E6=9C=8D=E5=8A=A1=E5=99=A8?= =?UTF-8?q?=E9=83=A8=E7=BD=B2=E6=96=87=E6=A1=A3=20DEPLOY=5FSERVER.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- DEPLOY_SERVER.md | 582 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 582 insertions(+) create mode 100644 DEPLOY_SERVER.md diff --git a/DEPLOY_SERVER.md b/DEPLOY_SERVER.md new file mode 100644 index 00000000..f7cc6fa7 --- /dev/null +++ b/DEPLOY_SERVER.md @@ -0,0 +1,582 @@ +# StarFireAPI 服务器部署文档 + +## 环境要求 + +- Docker 20.10+ +- Docker Compose 1.29+ 或 Docker Compose V2 +- Git +- 端口 6580 可用 +- 外部 Redis 服务（可选，已配置为 107.175.54.36:6379） + +--- + +## 快速部署（一键脚本） + +```bash +# 1. 克隆代码 +git clone https://git.586vip.cn/oadmin/xinghuoapi.git +cd xinghuoapi + +# 2. 配置环境变量 +cd deploy +cp .env.example .env + +# 3. 修改配置（必须修改） +vi .env +# 必须修改的配置项： +# - POSTGRES_PASSWORD=oadmin@123 +# - REDIS_HOST=107.175.54.36 +# - REDIS_PASSWORD=redis_JCHeKT +# - ADMIN_EMAIL=maticarmy@gmail.com +# - ADMIN_PASSWORD=oadmin@123 + +# 4. 返回项目根目录构建镜像 +cd .. +docker build -t starfireapi:latest . + +# 5. 修改 docker-compose.yml 使用本地镜像 +cd deploy +sed -i 's|image: weishaw/sub2api:latest|image: starfireapi:latest|g' docker-compose.yml + +# 6. 启动服务 +docker-compose up -d + +# 7. 查看日志 +docker-compose logs -f sub2api +``` + +--- + +## 详细部署步骤 + +### 1. 克隆代码 + +```bash +cd /opt +git clone https://git.586vip.cn/oadmin/xinghuoapi.git +cd xinghuoapi +``` + +### 2. 配置环境变量 + +```bash +cd deploy +cp .env.example .env +``` + +编辑 `.env` 文件，设置以下关键配置： + +```bash +# =========================================== +# 服务器配置 +# =========================================== +BIND_HOST=0.0.0.0 +SERVER_PORT=6580 +SERVER_MODE=release +RUN_MODE=standard +TZ=Asia/Shanghai + +# =========================================== +# PostgreSQL 数据库配置 +# =========================================== +POSTGRES_USER=sub2api +POSTGRES_PASSWORD=oadmin@123 +POSTGRES_DB=sub2api + +# =========================================== +# Redis 配置（外部Redis） +# =========================================== +REDIS_HOST=107.175.54.36 +REDIS_PORT=6379 +REDIS_PASSWORD=redis_JCHeKT +REDIS_DB=0 + +# =========================================== +# 管理员账号 +# =========================================== +ADMIN_EMAIL=maticarmy@gmail.com +ADMIN_PASSWORD=oadmin@123 + +# =========================================== +# JWT 配置（建议设置固定值） +# =========================================== +JWT_SECRET= # 留空自动生成，或使用 openssl rand -hex 32 生成 +JWT_EXPIRE_HOUR=24 + +# =========================================== +# 安全配置 +# =========================================== +SECURITY_URL_ALLOWLIST_ENABLED=false +SECURITY_URL_ALLOWLIST_ALLOW_INSECURE_HTTP=true +SECURITY_URL_ALLOWLIST_ALLOW_PRIVATE_HOSTS=true +``` + +### 3. 构建本地镜像 + +```bash +cd /opt/xinghuoapi + +# 构建镜像（会使用修改后的代码，前端显示 StarFireAPI） +docker build -t starfireapi:latest . +``` + +构建过程需要几分钟，请耐心等待。 + +### 4. 修改 docker-compose.yml 使用本地镜像 + +```bash +cd deploy + +# 自动替换镜像名称 +sed -i 's|image: weishaw/sub2api:latest|image: starfireapi:latest|g' docker-compose.yml + +# 确认修改成功 +grep "image: starfireapi" docker-compose.yml +# 应该输出： image: starfireapi:latest +``` + +### 5. 启动服务 + +```bash +cd /opt/xinghuoapi/deploy + +# 启动所有服务 +docker-compose up -d + +# 查看容器状态 +docker-compose ps + +# 应该看到 2 个容器： +# - sub2api (Up) +# - sub2api-postgres (Up) +``` + +### 6. 查看日志 + +```bash +# 查看所有日志 +docker-compose logs -f + +# 只查看应用日志 +docker-compose logs -f sub2api + +# 查看最近 100 行日志 +docker-compose logs --tail 100 sub2api +``` + +启动成功的标志： +``` +✓ Database connection successful +✓ Redis connection successful +✓ Starting server on 0.0.0.0:8080 +``` + +--- + +## 访问服务 + +**访问地址：** http://107.175.54.36:6580 + +**管理员登录：** +- **邮箱：** maticarmy@gmail.com +- **密码：** oadmin@123 + +--- + +## 常用管理命令 + +### 查看服务状态 + +```bash +cd /opt/xinghuoapi/deploy +docker-compose ps +``` + +### 停止服务 + +```bash +docker-compose down +``` + +### 重启服务 + +```bash +docker-compose restart + +# 或重启单个服务 +docker-compose restart sub2api +``` + +### 查看日志 + +```bash +# 实时查看日志 +docker-compose logs -f sub2api + +# 查看最近 N 行日志 +docker-compose logs --tail 50 sub2api + +# 查看所有服务日志 +docker-compose logs -f +``` + +### 更新代码 + +```bash +cd /opt/xinghuoapi + +# 1. 拉取最新代码 +git pull origin main + +# 2. 重新构建镜像 +docker build -t starfireapi:latest . + +# 3. 重启服务 +cd deploy +docker-compose down +docker-compose up -d + +# 4. 查看日志确认 +docker-compose logs -f sub2api +``` + +### 清空数据库重新初始化 + +```bash +cd /opt/xinghuoapi/deploy + +# 停止服务 +docker-compose down + +# 删除数据卷（会清空所有数据！） +docker volume rm deploy_postgres_data deploy_sub2api_data + +# 重新启动（会重新初始化数据库） +docker-compose up -d + +# 查看日志 +docker-compose logs -f sub2api +``` + +### 进入容器调试 + +```bash +# 进入应用容器 +docker exec -it sub2api sh + +# 进入数据库容器 +docker exec -it sub2api-postgres psql -U sub2api -d sub2api + +# 查看数据库中的用户 +SELECT id, email, role, created_at FROM users; +\q +``` + +--- + +## 故障排查 + +### 1. 容器一直重启 (Restarting) + +```bash +# 查看详细日志 +docker logs sub2api + +# 常见原因： +# - Redis 连接失败：检查 REDIS_HOST 和 REDIS_PASSWORD +# - 数据库连接失败：检查 POSTGRES_PASSWORD +# - 端口被占用：检查 6580 端口是否被占用 +``` + +### 2. Redis 连接超时 + +```bash +# 检查 Redis 是否可访问 +telnet 107.175.54.36 6379 + +# 如果连接失败，修改 .env 文件中的 REDIS_HOST +# 可以尝试： +# - 宿主机IP（hostname -I） +# - Redis容器名称（需要在同一网络） +# - Redis容器真实IP（docker inspect 查看） +``` + +### 3. 无法访问 Web 界面 + +```bash +# 检查端口是否开放 +netstat -tlnp | grep 6580 + +# 检查容器端口映射 +docker ps | grep sub2api + +# 检查防火墙 +ufw status +ufw allow 6580/tcp + +# 或 +firewall-cmd --list-ports +firewall-cmd --permanent --add-port=6580/tcp +firewall-cmd --reload +``` + +### 4. 密码不对 + +管理员密码是首次启动时创建的，修改 `.env` 不会更新已存在的账号。 + +解决方法： +```bash +cd /opt/xinghuoapi/deploy + +# 方案1：清空数据库重建（推荐） +docker-compose down +docker volume rm deploy_postgres_data deploy_sub2api_data +docker-compose up -d + +# 方案2：查看首次启动时自动生成的密码 +docker logs sub2api 2>&1 | grep "Generated admin password" +``` + +--- + +## 配置说明 + +### 端口配置 + +- **宿主机端口：** 6580 +- **容器内端口：** 8080 +- **映射关系：** `0.0.0.0:6580 → 容器:8080` + +### 数据持久化 + +Docker Volumes： +- `deploy_sub2api_data` - 应用数据（配置文件等） +- `deploy_postgres_data` - PostgreSQL 数据库数据 +- `deploy_redis_data` - Redis 数据（未使用，因为用的外部Redis） + +数据目录： +```bash +# 查看数据卷位置 +docker volume inspect deploy_postgres_data +docker volume inspect deploy_sub2api_data + +# 备份数据库 +docker exec sub2api-postgres pg_dump -U sub2api sub2api > backup_$(date +%Y%m%d).sql + +# 恢复数据库 +docker exec -i sub2api-postgres psql -U sub2api sub2api < backup_20260115.sql +``` + +--- + +## 网络架构 + +``` +外网访问 + ↓ +107.175.54.36:6580 + ↓ +[sub2api 容器:8080] + ↓ + ├─→ [sub2api-postgres:5432] (内部网络) + └─→ [外部Redis 107.175.54.36:6379] +``` + +--- + +## 服务器信息 + +- **服务器IP：** 107.175.54.36 +- **服务端口：** 6580 +- **Redis地址：** 107.175.54.36:6379 +- **Redis密码：** redis_JCHeKT +- **部署目录：** /opt/xinghuoapi +- **Git仓库：** https://git.586vip.cn/oadmin/xinghuoapi.git + +--- + +## 关键文件位置 + +``` +/opt/xinghuoapi/ +├── deploy/ +│ ├── .env # 环境变量配置（需手动创建） +│ ├── .env.example # 环境变量模板 +│ ├── docker-compose.yml # Docker编排配置 +│ └── config.example.yaml # 配置文件示例 +├── frontend/ # 前端代码（已修改为StarFireAPI） +│ ├── index.html +│ └── src/i18n/locales/ +│ ├── zh.ts # 中文界面 +│ └── en.ts # 英文界面 +├── backend/ # 后端Go代码 +├── Dockerfile # Docker镜像构建文件 +└── DEPLOY_SERVER.md # 本文档 +``` + +--- + +## 生产环境建议 + +### 1. 安全加固 + +```bash +# 1. 设置强密码 +# 修改 .env 中的： +# - POSTGRES_PASSWORD +# - REDIS_PASSWORD +# - ADMIN_PASSWORD +# - JWT_SECRET + +# 2. 限制数据库和Redis只监听内网 +# 3. 启用防火墙，只开放必要端口 +# 4. 定期更新镜像和依赖 +``` + +### 2. 备份策略 + +```bash +# 数据库定时备份脚本 +cat > /opt/xinghuoapi/backup.sh << 'EOF' +#!/bin/bash +BACKUP_DIR=/opt/xinghuoapi/backups +mkdir -p $BACKUP_DIR +DATE=$(date +%Y%m%d_%H%M%S) +docker exec sub2api-postgres pg_dump -U sub2api sub2api | gzip > $BACKUP_DIR/backup_${DATE}.sql.gz +# 保留最近7天的备份 +find $BACKUP_DIR -name "backup_*.sql.gz" -mtime +7 -delete +EOF + +chmod +x /opt/xinghuoapi/backup.sh + +# 添加到 crontab（每天凌晨2点备份） +echo "0 2 * * * /opt/xinghuoapi/backup.sh" | crontab - +``` + +### 3. 监控告警 + +```bash +# 监控容器状态 +docker-compose ps + +# 监控资源使用 +docker stats sub2api sub2api-postgres + +# 监控日志错误 +docker-compose logs --tail 100 sub2api | grep -i error +``` + +--- + +## 常见问题 FAQ + +**Q: 如何修改端口？** +```bash +# 修改 .env 文件 +SERVER_PORT=新端口号 +# 重启服务 +docker-compose down && docker-compose up -d +``` + +**Q: 如何使用内置Redis而不是外部Redis？** +```bash +# 1. 编辑 docker-compose.yml，取消注释 redis 服务 +# 2. 修改 .env： +REDIS_HOST=redis +REDIS_PASSWORD=设置一个密码 +# 3. 重启服务 +``` + +**Q: 如何查看数据库中的数据？** +```bash +docker exec -it sub2api-postgres psql -U sub2api -d sub2api +\dt # 查看所有表 +\d users # 查看users表结构 +SELECT * FROM users LIMIT 10; +\q +``` + +**Q: 如何重置管理员密码？** +参考上面的"故障排查 - 密码不对"部分。 + +--- + +## 更新日志 + +- 2026-01-15: 初始部署文档创建 +- 前端显示名称：StarFireAPI +- 服务器IP: 107.175.54.36 +- 服务端口: 6580 +- 外部Redis: 107.175.54.36:6379 + +--- + +## 技术支持 + +- Git仓库：https://git.586vip.cn/oadmin/xinghuoapi.git +- 上游项目：https://github.com/Wei-Shaw/sub2api + +--- + +## 附录：完整部署命令（复制粘贴执行） + +```bash +#!/bin/bash +set -e + +echo "开始部署 StarFireAPI..." + +# 1. 克隆代码 +cd /opt +git clone https://git.586vip.cn/oadmin/xinghuoapi.git || (cd xinghuoapi && git pull origin main) +cd xinghuoapi + +# 2. 配置环境变量 +cd deploy +if [ ! -f .env ]; then + cp .env.example .env + echo "请编辑 .env 文件，设置以下配置：" + echo " - POSTGRES_PASSWORD" + echo " - REDIS_HOST" + echo " - REDIS_PASSWORD" + echo " - ADMIN_EMAIL" + echo " - ADMIN_PASSWORD" + echo "" + echo "编辑完成后，重新运行此脚本" + exit 1 +fi + +# 3. 构建镜像 +cd /opt/xinghuoapi +echo "构建 StarFireAPI 镜像..." +docker build -t starfireapi:latest . + +# 4. 修改 docker-compose.yml +cd deploy +sed -i 's|image: weishaw/sub2api:latest|image: starfireapi:latest|g' docker-compose.yml +grep -q "image: starfireapi:latest" docker-compose.yml && echo "✓ docker-compose.yml 已更新" + +# 5. 启动服务 +echo "启动服务..." +docker-compose down +docker-compose up -d + +# 6. 等待服务启动 +echo "等待服务启动..." +sleep 10 + +# 7. 查看状态 +docker-compose ps +echo "" +echo "部署完成！" +echo "访问地址: http://$(hostname -I | awk '{print $1}'):6580" +echo "" +echo "查看日志: docker-compose logs -f sub2api" +``` + +保存为 `/opt/xinghuoapi/deploy.sh`，赋予执行权限后运行： + +```bash +chmod +x /opt/xinghuoapi/deploy.sh +./deploy.sh +```