xinghuoapi/DEPLOY_SERVER.md

# 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
```