xinghuoapi/DEPLOY_SERVER.md

StarFireAPI 服务器部署文档

环境要求

• Docker 20.10+
• Docker Compose 1.29+ 或 Docker Compose V2
• Git
• 端口 6580 可用
• 外部 Redis 服务（可选，已配置为 107.175.54.36:6379）

---

快速部署（一键脚本）

# 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. 克隆代码

cd /opt
git clone https://git.586vip.cn/oadmin/xinghuoapi.git
cd xinghuoapi

2. 配置环境变量

cd deploy
cp .env.example .env

编辑 .env 文件，设置以下关键配置：

# ===========================================
# 服务器配置
# ===========================================
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. 构建本地镜像

cd /opt/xinghuoapi

# 构建镜像（会使用修改后的代码，前端显示 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 "image: starfireapi" docker-compose.yml
# 应该输出：    image: starfireapi:latest

5. 启动服务

cd /opt/xinghuoapi/deploy

# 启动所有服务
docker-compose up -d

# 查看容器状态
docker-compose ps

# 应该看到 2 个容器：
# - sub2api (Up)
# - sub2api-postgres (Up)

6. 查看日志

# 查看所有日志
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

---

常用管理命令

查看服务状态

cd /opt/xinghuoapi/deploy
docker-compose ps

停止服务

docker-compose down

重启服务

docker-compose restart

# 或重启单个服务
docker-compose restart sub2api

查看日志

# 实时查看日志
docker-compose logs -f sub2api

# 查看最近 N 行日志
docker-compose logs --tail 50 sub2api

# 查看所有服务日志
docker-compose logs -f

更新代码

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

清空数据库重新初始化

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

进入容器调试

# 进入应用容器
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)

# 查看详细日志
docker logs sub2api

# 常见原因：
# - Redis 连接失败：检查 REDIS_HOST 和 REDIS_PASSWORD
# - 数据库连接失败：检查 POSTGRES_PASSWORD
# - 端口被占用：检查 6580 端口是否被占用

2. Redis 连接超时

# 检查 Redis 是否可访问
telnet 107.175.54.36 6379

# 如果连接失败，修改 .env 文件中的 REDIS_HOST
# 可以尝试：
# - 宿主机IP（hostname -I）
# - Redis容器名称（需要在同一网络）
# - Redis容器真实IP（docker inspect 查看）

3. 无法访问 Web 界面

# 检查端口是否开放
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 不会更新已存在的账号。

解决方法：

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）

数据目录：

# 查看数据卷位置
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. 安全加固

# 1. 设置强密码
# 修改 .env 中的：
# - POSTGRES_PASSWORD
# - REDIS_PASSWORD
# - ADMIN_PASSWORD
# - JWT_SECRET

# 2. 限制数据库和Redis只监听内网
# 3. 启用防火墙，只开放必要端口
# 4. 定期更新镜像和依赖

2. 备份策略

# 数据库定时备份脚本
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. 监控告警

# 监控容器状态
docker-compose ps

# 监控资源使用
docker stats sub2api sub2api-postgres

# 监控日志错误
docker-compose logs --tail 100 sub2api | grep -i error

---

常见问题 FAQ

Q: 如何修改端口？

# 修改 .env 文件
SERVER_PORT=新端口号
# 重启服务
docker-compose down && docker-compose up -d

Q: 如何使用内置Redis而不是外部Redis？

# 1. 编辑 docker-compose.yml，取消注释 redis 服务
# 2. 修改 .env：
REDIS_HOST=redis
REDIS_PASSWORD=设置一个密码
# 3. 重启服务

Q: 如何查看数据库中的数据？

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

---

附录：完整部署命令（复制粘贴执行）

#!/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，赋予执行权限后运行：

chmod +x /opt/xinghuoapi/deploy.sh
./deploy.sh