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)
421 lines
8.5 KiB
Markdown
421 lines
8.5 KiB
Markdown
# Sub2API 双 Remote Git 配置指南
|
||
|
||
## 📋 Git 仓库配置
|
||
|
||
### Remote 配置结构
|
||
|
||
```
|
||
upstream (官方仓库)
|
||
└── https://github.com/Wei-Shaw/sub2api.git
|
||
用途: 拉取官方更新
|
||
|
||
origin (你的仓库)
|
||
└── https://git.586vip.cn/oadmin/sub2api.git
|
||
用途: 保存你的二次开发代码
|
||
```
|
||
|
||
---
|
||
|
||
## 🚀 快速部署（一键完成）
|
||
|
||
### 方式 1：使用自动化脚本（推荐）
|
||
|
||
**在服务器上执行以下命令：**
|
||
|
||
```bash
|
||
# 下载部署脚本
|
||
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：手动分步执行
|
||
|
||
如果自动脚本有问题，可以手动执行：
|
||
|
||
```bash
|
||
# 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`：
|
||
|
||
```bash
|
||
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` 配置：
|
||
|
||
```bash
|
||
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 "===================="
|
||
```
|
||
|
||
启动服务：
|
||
|
||
```bash
|
||
# 拉取镜像
|
||
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
|
||
```
|
||
|
||
---
|
||
|
||
## 🔄 日常工作流程
|
||
|
||
### 开发流程
|
||
|
||
```bash
|
||
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
|
||
```
|
||
|
||
### 同步官方更新
|
||
|
||
```bash
|
||
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
|
||
```
|
||
|
||
### 查看分支和远程信息
|
||
|
||
```bash
|
||
# 查看所有分支
|
||
git branch -a
|
||
|
||
# 查看远程仓库
|
||
git remote -v
|
||
|
||
# 查看当前状态
|
||
git status
|
||
|
||
# 查看提交历史
|
||
git log --oneline --graph --all -10
|
||
```
|
||
|
||
---
|
||
|
||
## 🛠️ 常见操作
|
||
|
||
### 回滚到某个版本
|
||
|
||
```bash
|
||
# 查看提交历史
|
||
git log --oneline
|
||
|
||
# 回滚到指定提交（软回滚，保留修改）
|
||
git reset --soft <commit-hash>
|
||
|
||
# 回滚到指定提交（硬回滚，丢弃修改）
|
||
git reset --hard <commit-hash>
|
||
|
||
# 推送到远程（需要强制推送）
|
||
git push -f origin main
|
||
```
|
||
|
||
### 对比官方版本
|
||
|
||
```bash
|
||
# 对比特定文件
|
||
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
|
||
```
|
||
|
||
### 从官方仓库拉取特定分支/标签
|
||
|
||
```bash
|
||
# 拉取官方的所有标签
|
||
git fetch upstream --tags
|
||
|
||
# 查看所有标签
|
||
git tag -l
|
||
|
||
# 基于某个标签创建分支
|
||
git checkout -b v1.0.0 tags/v1.0.0
|
||
|
||
# 切回主分支
|
||
git checkout main
|
||
```
|
||
|
||
---
|
||
|
||
## 📦 Docker 管理
|
||
|
||
### 服务管理
|
||
|
||
```bash
|
||
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
|
||
```
|
||
|
||
### 更新镜像
|
||
|
||
```bash
|
||
# 拉取最新镜像
|
||
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 问题
|
||
|
||
```bash
|
||
# 如果 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 问题
|
||
|
||
```bash
|
||
# 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
|
||
```
|
||
|
||
---
|
||
|
||
## 📞 快速命令速查
|
||
|
||
```bash
|
||
# 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 # 停止
|
||
```
|