e4db851b31
- 添加双 Git remote 配置指南 (GIT_GUIDE.md, GIT_WORKFLOW.md) - 添加 1Panel 环境部署配置 (docker-compose.1panel.yml, .env.1panel) - 添加自动化部署脚本 (deploy-complete.sh, deploy-dev.sh, deploy.sh) - 添加部署说明文档 (README_DEPLOY.md) - 配置端口 2080 映射 - 支持连接现有 1Panel Redis (1Panel-redis-S1KH)
5.8 KiB
5.8 KiB
Sub2API 二次开发指南
🔧 Git 工作流程
初始设置
# 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
远程仓库配置结果
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：查看官方更新
# 拉取官方最新代码
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：合并官方更新
# 确保工作区干净
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（更清晰的历史）
# 拉取官方更新
git fetch upstream
# 将你的提交重放到官方最新代码之上
git rebase upstream/main
# 如果有冲突，解决后：
git add .
git rebase --continue
# 强制推送到你的仓库（注意：rebase 会改变历史）
git push -f origin dev
📦 部署流程
生产环境部署
cd /opt/sub2api-dev/deploy
# 运行自动部署脚本
chmod +x deploy-dev.sh
bash deploy-dev.sh
手动部署
# 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. 修改后端逻辑
# 修改代码
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. 修改前端界面
# 修改代码
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. 添加新功能
# 创建功能分支
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 对比
# 安装 VS Code Remote SSH 插件
# 然后在 VS Code 中：
# 1. 连接到服务器
# 2. 打开 /opt/sub2api-dev
# 3. 使用 Git 功能对比差异
命令行对比
# 对比某个文件
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
⚠️ 注意事项
- 定期同步: 建议每周拉取一次官方更新
- 冲突处理: 遇到冲突时，优先保留官方的核心逻辑，调整你的二开代码
- 分支管理: 重要功能单独开分支，测试通过后再合并
- 备份数据: 更新前备份数据库和配置文件
- 测试环境: 建议先在测试环境验证更新，再应用到生产
📋 常用命令速查
# 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 # 启动