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)
277 lines
5.8 KiB
Markdown
277 lines
5.8 KiB
Markdown
# 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 # 启动
|
||
```
|