# Sub2API 二次开发指南

## 🔧 Git 工作流程

### 初始设置

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

# 2. 配置远程仓库
git remote rename origin upstream  # 官方仓库改名为 upstream
git remote add origin https://your-git.com/your-repo.git  # 添加你的仓库

# 3. 创建开发分支
git checkout -b dev

# 4. 推送到你的仓库
git push -u origin dev
```

### 远程仓库配置结果

```bash
git remote -v
# upstream  https://github.com/Wei-Shaw/sub2api.git (fetch)
# upstream  https://github.com/Wei-Shaw/sub2api.git (push)
# origin    https://your-git.com/your-repo.git (fetch)
# origin    https://your-git.com/your-repo.git (push)
```

---

## 🔄 同步官方更新

### 方式 1：查看官方更新

```bash
# 拉取官方最新代码
git fetch upstream

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

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

# 查看某个文件的差异
git diff HEAD..upstream/main -- backend/internal/service/gateway_service.go
```

### 方式 2：合并官方更新

```bash
# 确保工作区干净
git status

# 提交你的修改
git add .
git commit -m "feat: 我的二开功能"

# 拉取并合并官方更新
git fetch upstream
git merge upstream/main

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

# 推送到你的仓库
git push origin dev
```

### 方式 3：使用 Rebase（更清晰的历史）

```bash
# 拉取官方更新
git fetch upstream

# 将你的提交重放到官方最新代码之上
git rebase upstream/main

# 如果有冲突，解决后：
git add .
git rebase --continue

# 强制推送到你的仓库（注意：rebase 会改变历史）
git push -f origin dev
```

---

## 📦 部署流程

### 生产环境部署

```bash
cd /opt/sub2api-dev/deploy

# 运行自动部署脚本
chmod +x deploy-dev.sh
bash deploy-dev.sh
```

### 手动部署

```bash
# 1. 进入部署目录
cd /opt/sub2api-dev/deploy

# 2. 创建配置（如果没有）
cp docker-compose.yml docker-compose.prod.yml
cp .env.example .env

# 3. 修改配置
nano docker-compose.prod.yml  # 改端口为 2080，配置 Redis
nano .env  # 设置密码等

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

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

---

## 🛠️ 开发建议

### 目录结构

```
sub2api-dev/
├── .git/                    # Git 仓库
├── backend/                 # 后端代码（Go）
│   ├── cmd/server/          # 入口
│   ├── internal/            # 核心逻辑
│   └── ent/                 # 数据模型
├── frontend/                # 前端代码（Vue）
│   └── src/
└── deploy/                  # 部署配置
    ├── docker-compose.prod.yml
    ├── .env
    └── deploy-dev.sh
```

### 常见二开场景

#### 1. 修改后端逻辑

```bash
# 修改代码
vim backend/internal/service/gateway_service.go

# 提交
git add backend/
git commit -m "feat: 修改网关逻辑"

# 重新构建镜像（如果需要）
cd backend
docker build -t sub2api:custom .

# 修改 docker-compose.prod.yml 使用自定义镜像
# image: sub2api:custom

# 重启服务
cd ../deploy
docker-compose -f docker-compose.prod.yml up -d
```

#### 2. 修改前端界面

```bash
# 修改代码
vim frontend/src/views/HomeView.vue

# 本地测试
cd frontend
npm install
npm run dev

# 构建
npm run build

# 提交
git add frontend/
git commit -m "feat: 修改首页界面"

# 后端重新构建（前端会被嵌入）
cd ../backend
go build -tags embed -o sub2api ./cmd/server
```

#### 3. 添加新功能

```bash
# 创建功能分支
git checkout -b feature/new-feature

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

# 合并到开发分支
git checkout dev
git merge feature/new-feature

# 推送
git push origin dev
```

---

## 🔍 对比工具

### 使用 VS Code 对比

```bash
# 安装 VS Code Remote SSH 插件
# 然后在 VS Code 中：
# 1. 连接到服务器
# 2. 打开 /opt/sub2api-dev
# 3. 使用 Git 功能对比差异
```

### 命令行对比

```bash
# 对比某个文件
git diff upstream/main -- backend/internal/service/gateway_service.go

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

# 生成对比报告
git diff upstream/main > changes.patch

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

---

## ⚠️ 注意事项

1. **定期同步**: 建议每周拉取一次官方更新
2. **冲突处理**: 遇到冲突时，优先保留官方的核心逻辑，调整你的二开代码
3. **分支管理**: 重要功能单独开分支，测试通过后再合并
4. **备份数据**: 更新前备份数据库和配置文件
5. **测试环境**: 建议先在测试环境验证更新，再应用到生产

---

## 📋 常用命令速查

```bash
# Git 管理
git status                      # 查看状态
git log --oneline -10          # 查看提交历史
git fetch upstream             # 拉取官方更新
git diff upstream/main         # 对比差异
git merge upstream/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     # 停止

# 服务管理
docker-compose -f docker-compose.prod.yml pull     # 更新镜像
docker-compose -f docker-compose.prod.yml up -d    # 启动
```