583 lines
12 KiB
Markdown
583 lines
12 KiB
Markdown
# 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
|
||
```
|