sub2api/GIT_GUIDE.md

Sub2API 双 Remote Git 配置指南

📋 Git 仓库配置

Remote 配置结构

upstream (官方仓库)
└── https://github.com/Wei-Shaw/sub2api.git
    用途: 拉取官方更新

origin (你的仓库)
└── https://git.586vip.cn/oadmin/sub2api.git
    用途: 保存你的二次开发代码

---

🚀 快速部署（一键完成）

方式 1：使用自动化脚本（推荐）

在服务器上执行以下命令：

# 下载部署脚本
curl -o /tmp/deploy-sub2api.sh https://你的脚本地址/deploy-complete.sh

# 或者直接创建脚本
cat > /tmp/deploy-sub2api.sh << 'SCRIPT_END'
# [这里粘贴 deploy-complete.sh 的全部内容]
SCRIPT_END

# 赋予执行权限
chmod +x /tmp/deploy-sub2api.sh

# 运行脚本
bash /tmp/deploy-sub2api.sh

脚本会自动完成：

• ✅ 克隆官方仓库
• ✅ 配置双 remote
• ✅ 推送到你的仓库
• ✅ 创建部署配置
• ✅ 启动 Docker 服务

---

方式 2：手动分步执行

如果自动脚本有问题，可以手动执行：

# 1. 克隆官方仓库
cd /opt
git clone https://github.com/Wei-Shaw/sub2api.git sub2api-dev
cd sub2api-dev

# 2. 配置 Git Remote
git remote rename origin upstream
git remote add origin https://git.586vip.cn/oadmin/sub2api.git

# 3. 查看配置
git remote -v
# 应该看到：
# origin    https://git.586vip.cn/oadmin/sub2api.git (fetch)
# origin    https://git.586vip.cn/oadmin/sub2api.git (push)
# upstream  https://github.com/Wei-Shaw/sub2api.git (fetch)
# upstream  https://github.com/Wei-Shaw/sub2api.git (push)

# 4. 创建 main 分支
git checkout -b main

# 5. 推送到你的仓库
git push -u origin main

# 6. 配置部署文件
cd deploy

创建 docker-compose.prod.yml：

cat > docker-compose.prod.yml << 'EOF'
services:
  sub2api:
    image: weishaw/sub2api:latest
    container_name: sub2api
    restart: unless-stopped
    ports:
      - "2080:8080"
    volumes:
      - ./data:/app/data
    environment:
      - AUTO_SETUP=true
      - SERVER_HOST=0.0.0.0
      - SERVER_PORT=8080
      - SERVER_MODE=release
      - DATABASE_HOST=postgres
      - DATABASE_PORT=5432
      - DATABASE_USER=sub2api
      - DATABASE_PASSWORD=${POSTGRES_PASSWORD}
      - DATABASE_DBNAME=sub2api
      - DATABASE_SSLMODE=disable
      - REDIS_HOST=host.docker.internal
      - REDIS_PORT=6379
      - REDIS_PASSWORD=redis_bJFKDk
      - REDIS_DB=1
      - ADMIN_EMAIL=${ADMIN_EMAIL}
      - ADMIN_PASSWORD=${ADMIN_PASSWORD}
      - JWT_SECRET=${JWT_SECRET}
      - TZ=Asia/Shanghai
    depends_on:
      - postgres
    extra_hosts:
      - "host.docker.internal:host-gateway"

  postgres:
    image: postgres:18-alpine
    container_name: sub2api-postgres
    restart: unless-stopped
    volumes:
      - postgres_data:/var/lib/postgresql/data
    environment:
      - POSTGRES_USER=sub2api
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
      - POSTGRES_DB=sub2api
      - TZ=Asia/Shanghai
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U sub2api"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  postgres_data:
EOF

创建 .env 配置：

cat > .env << EOF
POSTGRES_USER=sub2api
POSTGRES_PASSWORD=$(openssl rand -base64 24)
POSTGRES_DB=sub2api
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=admin123
JWT_SECRET=$(openssl rand -hex 32)
JWT_EXPIRE_HOUR=24
TZ=Asia/Shanghai
SERVER_MODE=release
RUN_MODE=standard
EOF

# 显示生成的密码
echo "===== 配置信息 ====="
cat .env
echo "===================="

启动服务：

# 拉取镜像
docker-compose -f docker-compose.prod.yml pull

# 启动服务
docker-compose -f docker-compose.prod.yml up -d

# 查看日志
docker-compose -f docker-compose.prod.yml logs -f

---

🔄 日常工作流程

开发流程

cd /opt/sub2api-dev

# 1. 创建功能分支
git checkout -b feature/new-feature

# 2. 开发并提交
git add .
git commit -m "feat: 添加新功能"

# 3. 切回主分支
git checkout main

# 4. 合并功能分支
git merge feature/new-feature

# 5. 推送到你的仓库
git push origin main

# 6. 删除功能分支（可选）
git branch -d feature/new-feature

同步官方更新

cd /opt/sub2api-dev

# 1. 查看官方更新
git fetch upstream
git log HEAD..upstream/main --oneline

# 2. 查看详细差异
git diff HEAD..upstream/main

# 3. 合并官方更新
git merge upstream/main

# 4. 如果有冲突，解决后提交
git add .
git commit -m "merge: 合并官方更新 v1.x.x"

# 5. 推送到你的仓库
git push origin main

# 6. 重新部署（如果需要）
cd deploy
docker-compose -f docker-compose.prod.yml pull
docker-compose -f docker-compose.prod.yml up -d

查看分支和远程信息

# 查看所有分支
git branch -a

# 查看远程仓库
git remote -v

# 查看当前状态
git status

# 查看提交历史
git log --oneline --graph --all -10

---

🛠️ 常见操作

回滚到某个版本

# 查看提交历史
git log --oneline

# 回滚到指定提交（软回滚，保留修改）
git reset --soft <commit-hash>

# 回滚到指定提交（硬回滚，丢弃修改）
git reset --hard <commit-hash>

# 推送到远程（需要强制推送）
git push -f origin main

对比官方版本

# 对比特定文件
git diff upstream/main -- backend/internal/service/gateway_service.go

# 对比整个目录
git diff upstream/main -- backend/internal/service/

# 生成 patch 文件
git diff upstream/main > my-changes.patch

# 查看改动的文件列表
git diff --name-only upstream/main

从官方仓库拉取特定分支/标签

# 拉取官方的所有标签
git fetch upstream --tags

# 查看所有标签
git tag -l

# 基于某个标签创建分支
git checkout -b v1.0.0 tags/v1.0.0

# 切回主分支
git checkout main

---

📦 Docker 管理

服务管理

cd /opt/sub2api-dev/deploy

# 查看状态
docker-compose -f docker-compose.prod.yml ps

# 查看日志
docker-compose -f docker-compose.prod.yml logs -f

# 只看 sub2api 日志
docker-compose -f docker-compose.prod.yml logs -f sub2api

# 重启服务
docker-compose -f docker-compose.prod.yml restart

# 停止服务
docker-compose -f docker-compose.prod.yml down

# 完全清理（包括数据）
docker-compose -f docker-compose.prod.yml down -v

更新镜像

# 拉取最新镜像
docker-compose -f docker-compose.prod.yml pull

# 重新创建容器
docker-compose -f docker-compose.prod.yml up -d

# 查看镜像信息
docker images | grep sub2api

---

⚠️ 注意事项

1. 定期备份

   • 备份 .env 文件
   • 导出 PostgreSQL 数据库
   • 提交代码到远程仓库

2. 合并冲突处理

   • 遇到冲突时，优先保留官方核心逻辑
   • 调整你的二开代码以适配官方更新

3. 测试环境

   • 建议先在测试环境验证更新
   • 确认无误后再应用到生产环境

4. 版本管理

   • 重要功能单独开分支
   • 使用有意义的提交信息
   • 定期推送到远程仓库

---

🔍 故障排查

Git 问题

# 如果 push 被拒绝
git pull origin main --rebase
git push origin main

# 如果需要强制推送（危险！）
git push -f origin main

# 查看 Git 配置
git config --list

# 重置 remote
git remote remove origin
git remote add origin https://git.586vip.cn/oadmin/sub2api.git

Docker 问题

# Redis 连接失败
# 修改 docker-compose.prod.yml 中的 REDIS_HOST
# 从 host.docker.internal 改为 172.17.0.1

# 查看容器详细信息
docker inspect sub2api

# 进入容器调试
docker exec -it sub2api sh

# 查看网络
docker network ls
docker network inspect bridge

---

📞 快速命令速查

# Git
git status                              # 状态
git fetch upstream                      # 拉取官方更新
git merge upstream/main                 # 合并更新
git push origin main                    # 推送到你的仓库

# Docker
docker-compose -f docker-compose.prod.yml ps        # 状态
docker-compose -f docker-compose.prod.yml logs -f   # 日志
docker-compose -f docker-compose.prod.yml restart   # 重启
docker-compose -f docker-compose.prod.yml down      # 停止