From e4db851b3163b3b0f164610bb388495a8842b5ce Mon Sep 17 00:00:00 2001
From: huangzhenpc <huangzhenpc@586vip.cn>
Date: Sun, 4 Jan 2026 10:25:36 +0800
Subject: [PATCH] =?UTF-8?q?feat:=20=E6=B7=BB=E5=8A=A0=E4=BA=8C=E6=AC=A1?=
 =?UTF-8?q?=E5=BC=80=E5=8F=91=E9=83=A8=E7=BD=B2=E9=85=8D=E7=BD=AE=E5=92=8C?=
 =?UTF-8?q?=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 添加双 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)
---
 GIT_GUIDE.md                     | 420 +++++++++++++++++++++++++++++++
 GIT_WORKFLOW.md                  | 276 ++++++++++++++++++++
 deploy/.env.1panel               |  51 ++++
 deploy/README_DEPLOY.md          | 136 ++++++++++
 deploy/deploy-complete.sh        | 221 ++++++++++++++++
 deploy/deploy-dev.sh             | 120 +++++++++
 deploy/deploy.sh                 | 104 ++++++++
 deploy/docker-compose.1panel.yml | 111 ++++++++
 8 files changed, 1439 insertions(+)
 create mode 100644 GIT_GUIDE.md
 create mode 100644 GIT_WORKFLOW.md
 create mode 100644 deploy/.env.1panel
 create mode 100644 deploy/README_DEPLOY.md
 create mode 100644 deploy/deploy-complete.sh
 create mode 100644 deploy/deploy-dev.sh
 create mode 100644 deploy/deploy.sh
 create mode 100644 deploy/docker-compose.1panel.yml

diff --git a/GIT_GUIDE.md b/GIT_GUIDE.md
new file mode 100644
index 00000000..99afe30b
--- /dev/null
+++ b/GIT_GUIDE.md
@@ -0,0 +1,420 @@
+# 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      # 停止
+```
diff --git a/GIT_WORKFLOW.md b/GIT_WORKFLOW.md
new file mode 100644
index 00000000..fbb8e568
--- /dev/null
+++ b/GIT_WORKFLOW.md
@@ -0,0 +1,276 @@
+# 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    # 启动
+```
diff --git a/deploy/.env.1panel b/deploy/.env.1panel
new file mode 100644
index 00000000..ca5bc8d8
--- /dev/null
+++ b/deploy/.env.1panel
@@ -0,0 +1,51 @@
+# =============================================================================
+# Sub2API 环境配置 - 1Panel 环境
+# =============================================================================
+
+# -----------------------------------------------------------------------------
+# Server Configuration
+# -----------------------------------------------------------------------------
+BIND_HOST=0.0.0.0
+SERVER_PORT=2080
+SERVER_MODE=release
+RUN_MODE=standard
+TZ=Asia/Shanghai
+
+# -----------------------------------------------------------------------------
+# PostgreSQL Configuration (REQUIRED - 请修改密码！)
+# -----------------------------------------------------------------------------
+POSTGRES_USER=sub2api
+POSTGRES_PASSWORD=请修改为你的强密码
+POSTGRES_DB=sub2api
+
+# -----------------------------------------------------------------------------
+# Redis Configuration - 使用你现有的 1Panel Redis
+# -----------------------------------------------------------------------------
+# 方式1：如果使用 Docker 网络连接，填写容器名
+REDIS_HOST=1Panel-redis-S1KH
+# 方式2：如果上面不行，使用宿主机 IP（需要你填写服务器的内网 IP）
+# REDIS_HOST=172.17.0.1
+REDIS_PORT=6379
+REDIS_PASSWORD=redis_bJFKDk
+REDIS_DB=1
+
+# -----------------------------------------------------------------------------
+# Admin Account
+# -----------------------------------------------------------------------------
+ADMIN_EMAIL=oadmin
+ADMIN_PASSWORD=oadmin@123
+
+# -----------------------------------------------------------------------------
+# JWT Configuration
+# -----------------------------------------------------------------------------
+# 使用下面的命令生成随机密钥：openssl rand -hex 32
+JWT_SECRET=1fb3a3533039e0d1ea693f0508bbffca44b7157370f11dfe33ce352a5f07039a
+JWT_EXPIRE_HOUR=24
+
+# -----------------------------------------------------------------------------
+# Gemini OAuth (可选 - 如果不使用 Gemini 可以忽略)
+# -----------------------------------------------------------------------------
+GEMINI_OAUTH_CLIENT_ID=
+GEMINI_OAUTH_CLIENT_SECRET=
+GEMINI_OAUTH_SCOPES=
+GEMINI_QUOTA_POLICY=
diff --git a/deploy/README_DEPLOY.md b/deploy/README_DEPLOY.md
new file mode 100644
index 00000000..b752fbe5
--- /dev/null
+++ b/deploy/README_DEPLOY.md
@@ -0,0 +1,136 @@
+# Sub2API 部署指南 - 端口 2080
+
+## 快速部署（推荐）
+
+### 1. 上传文件到服务器
+
+将 `deploy` 目录上传到服务器的 `/opt/sub2api`
+
+```bash
+# 在服务器上创建目录
+mkdir -p /opt/sub2api
+```
+
+### 2. 运行自动部署脚本
+
+```bash
+cd /opt/sub2api
+chmod +x deploy.sh
+bash deploy.sh
+```
+
+脚本会自动完成：
+- ✅ 生成安全的密码和密钥
+- ✅ 创建配置文件
+- ✅ 拉取 Docker 镜像
+- ✅ 启动服务
+
+### 3. 访问系统
+
+浏览器打开: `http://你的服务器IP:2080`
+
+默认账号:
+- 邮箱: `admin@example.com`
+- 密码: `admin123`
+
+---
+
+## 手动部署
+
+如果自动脚本失败，可以手动部署：
+
+```bash
+cd /opt/sub2api
+
+# 1. 复制配置文件
+cp docker-compose.2080.yml docker-compose.yml
+cp .env.2080 .env
+
+# 2. 生成密钥
+sed -i "s/POSTGRES_PASSWORD=.*/POSTGRES_PASSWORD=$(openssl rand -base64 24)/" .env
+sed -i "s/JWT_SECRET=.*/JWT_SECRET=$(openssl rand -hex 32)/" .env
+
+# 3. 启动服务
+docker-compose pull
+docker-compose up -d
+
+# 4. 查看日志
+docker-compose logs -f
+```
+
+---
+
+## 配置说明
+
+### 端口映射
+- 宿主机端口: `2080`
+- 容器内端口: `8080`
+
+### Redis 连接
+- 使用现有的 1Panel Redis: `1Panel-redis-S1KH`
+- 端口: `6379`
+- 密码: `redis_bJFKDk`
+- 数据库: `1` (避免与其他应用冲突)
+
+### PostgreSQL
+- 自动创建独立的 PostgreSQL 容器
+- 数据持久化在 Docker volume 中
+
+---
+
+## 常用命令
+
+```bash
+# 查看服务状态
+docker-compose ps
+
+# 查看日志
+docker-compose logs -f
+
+# 重启服务
+docker-compose restart
+
+# 停止服务
+docker-compose down
+
+# 更新到最新版本
+docker-compose pull
+docker-compose up -d
+```
+
+---
+
+## 故障排查
+
+### Redis 连接失败
+
+如果日志显示 Redis 连接失败，尝试修改 `docker-compose.yml`:
+
+将:
+```yaml
+- REDIS_HOST=host.docker.internal
+```
+
+改为:
+```yaml
+- REDIS_HOST=172.17.0.1
+```
+
+然后重启:
+```bash
+docker-compose down
+docker-compose up -d
+```
+
+### 查看详细日志
+
+```bash
+# 只看 sub2api 日志
+docker-compose logs sub2api
+
+# 只看 PostgreSQL 日志
+docker-compose logs postgres
+
+# 实时查看最新 50 行日志
+docker-compose logs -f --tail=50
+```
diff --git a/deploy/deploy-complete.sh b/deploy/deploy-complete.sh
new file mode 100644
index 00000000..50669588
--- /dev/null
+++ b/deploy/deploy-complete.sh
@@ -0,0 +1,221 @@
+#!/bin/bash
+
+# Sub2API 完整部署脚本 - 双 Git Remote 配置
+# 官方仓库: https://github.com/Wei-Shaw/sub2api.git
+# 你的仓库: https://git.586vip.cn/oadmin/sub2api.git
+
+set -e
+
+echo "=========================================="
+echo "  Sub2API 二次开发环境部署"
+echo "  端口: 2080"
+echo "  双 Remote Git 配置"
+echo "=========================================="
+echo ""
+
+# 检查是否已经存在项目目录
+if [ -d "/opt/sub2api-dev" ]; then
+    echo "⚠️  目录 /opt/sub2api-dev 已存在"
+    read -p "是否删除并重新部署？(y/N): " confirm
+    if [[ $confirm == [yY] ]]; then
+        rm -rf /opt/sub2api-dev
+    else
+        echo "❌ 取消部署"
+        exit 1
+    fi
+fi
+
+cd /opt
+
+# ===================================
+# 1. 克隆官方仓库
+# ===================================
+echo "📥 克隆官方仓库..."
+git clone https://github.com/Wei-Shaw/sub2api.git sub2api-dev
+cd sub2api-dev
+
+echo "✅ 官方仓库克隆完成"
+echo ""
+
+# ===================================
+# 2. 配置双 Remote
+# ===================================
+echo "🔧 配置 Git Remote..."
+
+# 将 origin 改名为 upstream（官方仓库）
+git remote rename origin upstream
+
+# 添加你的仓库为 origin
+git remote add origin https://git.586vip.cn/oadmin/sub2api.git
+
+# 显示配置结果
+echo "✅ Git Remote 配置完成:"
+git remote -v
+echo ""
+
+# ===================================
+# 3. 创建并切换到 main 分支
+# ===================================
+echo "🌿 创建 main 分支..."
+git checkout -b main
+
+echo "✅ 当前分支: $(git branch --show-current)"
+echo ""
+
+# ===================================
+# 4. 首次推送到你的仓库
+# ===================================
+echo "📤 推送到你的仓库..."
+git push -u origin main
+
+echo "✅ 代码已推送到: https://git.586vip.cn/oadmin/sub2api.git"
+echo ""
+
+# ===================================
+# 5. 配置部署文件
+# ===================================
+echo "📝 配置部署文件..."
+
+cd deploy
+
+# 创建生产环境 docker-compose 配置
+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
+
+echo "✅ docker-compose.prod.yml 已创建"
+
+# 创建 .env 文件
+if [ ! -f ".env" ]; then
+    echo "🔐 生成配置文件..."
+
+    POSTGRES_PASS=$(openssl rand -base64 24)
+    JWT_KEY=$(openssl rand -hex 32)
+
+    cat > .env << EOF
+# PostgreSQL 配置
+POSTGRES_USER=sub2api
+POSTGRES_PASSWORD=${POSTGRES_PASS}
+POSTGRES_DB=sub2api
+
+# 管理员账号
+ADMIN_EMAIL=admin@example.com
+ADMIN_PASSWORD=admin123
+
+# JWT 配置
+JWT_SECRET=${JWT_KEY}
+JWT_EXPIRE_HOUR=24
+
+# 其他配置
+TZ=Asia/Shanghai
+SERVER_MODE=release
+RUN_MODE=standard
+EOF
+
+    echo "✅ .env 文件已创建"
+    echo ""
+    echo "🔑 生成的密钥（请保存）:"
+    echo "   PostgreSQL 密码: ${POSTGRES_PASS}"
+    echo "   JWT Secret: ${JWT_KEY}"
+    echo ""
+fi
+
+# ===================================
+# 6. 启动 Docker 服务
+# ===================================
+echo "🐳 拉取 Docker 镜像..."
+docker-compose -f docker-compose.prod.yml pull
+
+echo ""
+echo "🚀 启动服务..."
+docker-compose -f docker-compose.prod.yml up -d
+
+echo ""
+echo "⏳ 等待服务启动..."
+sleep 15
+
+# ===================================
+# 7. 显示部署结果
+# ===================================
+echo ""
+echo "📊 服务状态:"
+docker-compose -f docker-compose.prod.yml ps
+
+echo ""
+echo "=========================================="
+echo "  ✅ 部署完成！"
+echo "=========================================="
+echo ""
+echo "🌐 访问信息:"
+echo "   URL: http://$(hostname -I | awk '{print $1}'):2080"
+echo "   管理员: admin@example.com / admin123"
+echo ""
+echo "📋 Git 配置:"
+echo "   官方仓库 (upstream): https://github.com/Wei-Shaw/sub2api.git"
+echo "   你的仓库 (origin):   https://git.586vip.cn/oadmin/sub2api.git"
+echo "   当前分支: main"
+echo ""
+echo "🔄 同步官方更新:"
+echo "   cd /opt/sub2api-dev"
+echo "   git fetch upstream"
+echo "   git merge upstream/main"
+echo "   git push origin main"
+echo ""
+echo "📝 常用命令:"
+echo "   查看日志: cd /opt/sub2api-dev/deploy && docker-compose -f docker-compose.prod.yml logs -f"
+echo "   重启服务: docker-compose -f docker-compose.prod.yml restart"
+echo "   停止服务: docker-compose -f docker-compose.prod.yml down"
+echo ""
+echo "🎉 访问 http://$(hostname -I | awk '{print $1}'):2080 开始使用！"
+echo ""
diff --git a/deploy/deploy-dev.sh b/deploy/deploy-dev.sh
new file mode 100644
index 00000000..ed760248
--- /dev/null
+++ b/deploy/deploy-dev.sh
@@ -0,0 +1,120 @@
+#!/bin/bash
+
+# Sub2API 二次开发部署脚本
+# 使用方法: bash deploy-dev.sh
+
+set -e
+
+echo "====================================="
+echo "  Sub2API 二开版本部署"
+echo "  端口: 2080"
+echo "====================================="
+echo ""
+
+# 检查是否在 Git 仓库中
+if [ ! -d ".git" ]; then
+    echo "❌ 错误: 当前目录不是 Git 仓库"
+    echo "请在项目根目录运行此脚本"
+    exit 1
+fi
+
+echo "📦 当前 Git 信息:"
+echo "   分支: $(git branch --show-current)"
+echo "   最新提交: $(git log -1 --oneline)"
+echo ""
+
+# 进入 deploy 目录
+cd deploy
+
+# 检查配置文件
+if [ ! -f "docker-compose.prod.yml" ]; then
+    echo "📝 创建生产环境配置..."
+    cp docker-compose.yml docker-compose.prod.yml
+
+    # 修改端口为 2080
+    sed -i 's/\${SERVER_PORT:-8080}/2080/' docker-compose.prod.yml
+
+    # 添加 extra_hosts 配置（连接宿主机 Redis）
+    if ! grep -q "extra_hosts" docker-compose.prod.yml; then
+        sed -i '/depends_on:/i\    extra_hosts:\n      - "host.docker.internal:host-gateway"' docker-compose.prod.yml
+    fi
+
+    # 修改 Redis 配置
+    sed -i 's/REDIS_HOST=redis/REDIS_HOST=host.docker.internal/' docker-compose.prod.yml
+    sed -i 's/REDIS_PASSWORD=\${REDIS_PASSWORD:-}/REDIS_PASSWORD=redis_bJFKDk/' docker-compose.prod.yml
+    sed -i 's/REDIS_DB=\${REDIS_DB:-0}/REDIS_DB=1/' docker-compose.prod.yml
+
+    echo "✅ docker-compose.prod.yml 已创建"
+fi
+
+# 创建 .env 文件
+if [ ! -f ".env" ]; then
+    echo "🔐 生成配置文件..."
+
+    cat > .env << EOF
+# PostgreSQL 配置
+POSTGRES_USER=sub2api
+POSTGRES_PASSWORD=$(openssl rand -base64 24)
+POSTGRES_DB=sub2api
+
+# 管理员账号
+ADMIN_EMAIL=admin@example.com
+ADMIN_PASSWORD=admin123
+
+# JWT 配置
+JWT_SECRET=$(openssl rand -hex 32)
+JWT_EXPIRE_HOUR=24
+
+# 其他配置
+TZ=Asia/Shanghai
+SERVER_MODE=release
+RUN_MODE=standard
+EOF
+
+    echo "✅ .env 文件已创建"
+    echo ""
+    echo "📋 生成的配置（请保存）:"
+    cat .env | grep -E "POSTGRES_PASSWORD|JWT_SECRET"
+    echo ""
+else
+    echo "⚠️  .env 已存在，跳过创建"
+fi
+
+# 拉取镜像
+echo ""
+echo "📥 拉取 Docker 镜像..."
+docker-compose -f docker-compose.prod.yml pull
+
+# 启动服务
+echo ""
+echo "🚀 启动服务..."
+docker-compose -f docker-compose.prod.yml up -d
+
+# 等待启动
+echo ""
+echo "⏳ 等待服务启动..."
+sleep 10
+
+# 显示状态
+echo ""
+echo "📊 服务状态:"
+docker-compose -f docker-compose.prod.yml ps
+
+echo ""
+echo "====================================="
+echo "  ✅ 部署完成！"
+echo "====================================="
+echo ""
+echo "📝 访问信息:"
+echo "   URL: http://$(hostname -I | awk '{print $1}'):2080"
+echo "   管理员: admin@example.com / admin123"
+echo ""
+echo "📋 常用命令:"
+echo "   查看日志: docker-compose -f docker-compose.prod.yml logs -f"
+echo "   重启服务: docker-compose -f docker-compose.prod.yml restart"
+echo "   停止服务: docker-compose -f docker-compose.prod.yml down"
+echo ""
+echo "🔄 同步官方更新:"
+echo "   git fetch upstream"
+echo "   git merge upstream/main"
+echo ""
diff --git a/deploy/deploy.sh b/deploy/deploy.sh
new file mode 100644
index 00000000..b9d25fd7
--- /dev/null
+++ b/deploy/deploy.sh
@@ -0,0 +1,104 @@
+#!/bin/bash
+
+# Sub2API 自动部署脚本 - 端口 2080
+# 使用方法: bash deploy.sh
+
+set -e
+
+echo "====================================="
+echo "  Sub2API 自动部署脚本"
+echo "  端口: 2080"
+echo "====================================="
+echo ""
+
+# 检查是否在正确的目录
+if [ ! -f "docker-compose.2080.yml" ]; then
+    echo "❌ 错误: 请在包含 docker-compose.2080.yml 的目录中运行此脚本"
+    exit 1
+fi
+
+# 检查 Docker 是否安装
+if ! command -v docker &> /dev/null; then
+    echo "❌ Docker 未安装，请先安装 Docker"
+    exit 1
+fi
+
+if ! command -v docker-compose &> /dev/null; then
+    echo "❌ Docker Compose 未安装，请先安装 Docker Compose"
+    exit 1
+fi
+
+echo "✅ Docker 环境检查通过"
+echo ""
+
+# 复制配置文件
+if [ ! -f ".env" ]; then
+    echo "📝 创建配置文件..."
+    cp .env.2080 .env
+
+    # 生成随机密码和密钥
+    echo "🔐 生成安全密钥..."
+    POSTGRES_PASS=$(openssl rand -base64 24)
+    JWT_KEY=$(openssl rand -hex 32)
+
+    # 更新 .env 文件
+    sed -i "s/POSTGRES_PASSWORD=.*/POSTGRES_PASSWORD=${POSTGRES_PASS}/" .env
+    sed -i "s/JWT_SECRET=.*/JWT_SECRET=${JWT_KEY}/" .env
+
+    echo "✅ 配置文件已创建: .env"
+    echo ""
+    echo "📋 生成的密码（请保存）:"
+    echo "   PostgreSQL 密码: ${POSTGRES_PASS}"
+    echo ""
+else
+    echo "⚠️  .env 文件已存在，跳过创建"
+    echo ""
+fi
+
+# 复制 docker-compose 文件
+if [ ! -f "docker-compose.yml" ]; then
+    echo "📝 创建 docker-compose.yml..."
+    cp docker-compose.2080.yml docker-compose.yml
+    echo "✅ docker-compose.yml 已创建"
+    echo ""
+fi
+
+# 拉取镜像
+echo "📥 拉取 Docker 镜像..."
+docker-compose pull
+
+# 启动服务
+echo ""
+echo "🚀 启动服务..."
+docker-compose up -d
+
+# 等待服务启动
+echo ""
+echo "⏳ 等待服务启动..."
+sleep 10
+
+# 检查服务状态
+echo ""
+echo "📊 服务状态:"
+docker-compose ps
+
+echo ""
+echo "====================================="
+echo "  ✅ 部署完成！"
+echo "====================================="
+echo ""
+echo "📝 访问信息:"
+echo "   URL: http://$(hostname -I | awk '{print $1}'):2080"
+echo "   管理员邮箱: admin@example.com"
+echo "   管理员密码: admin123"
+echo ""
+echo "⚠️  安全建议:"
+echo "   1. 登录后立即修改管理员密码"
+echo "   2. 如需修改配置，编辑 .env 文件后执行: docker-compose restart"
+echo ""
+echo "📋 常用命令:"
+echo "   查看日志: docker-compose logs -f"
+echo "   重启服务: docker-compose restart"
+echo "   停止服务: docker-compose down"
+echo ""
+echo "🎉 部署完成！请在浏览器中访问上述 URL"
diff --git a/deploy/docker-compose.1panel.yml b/deploy/docker-compose.1panel.yml
new file mode 100644
index 00000000..527e1ee0
--- /dev/null
+++ b/deploy/docker-compose.1panel.yml
@@ -0,0 +1,111 @@
+# =============================================================================
+# Sub2API Docker Compose - 1Panel 环境配置
+# =============================================================================
+# 此配置文件适用于已有 1Panel 环境，复用现有 Redis
+# =============================================================================
+
+services:
+  # ===========================================================================
+  # Sub2API Application
+  # ===========================================================================
+  sub2api:
+    image: weishaw/sub2api:latest
+    container_name: sub2api
+    restart: unless-stopped
+    ulimits:
+      nofile:
+        soft: 100000
+        hard: 100000
+    ports:
+      - "${BIND_HOST:-0.0.0.0}:${SERVER_PORT:-8080}:8080"
+    volumes:
+      - sub2api_data:/app/data
+    environment:
+      # Auto Setup
+      - AUTO_SETUP=true
+
+      # Server Configuration
+      - SERVER_HOST=0.0.0.0
+      - SERVER_PORT=8080
+      - SERVER_MODE=${SERVER_MODE:-release}
+      - RUN_MODE=${RUN_MODE:-standard}
+
+      # Database Configuration
+      - DATABASE_HOST=postgres
+      - DATABASE_PORT=5432
+      - DATABASE_USER=${POSTGRES_USER:-sub2api}
+      - DATABASE_PASSWORD=${POSTGRES_PASSWORD:?POSTGRES_PASSWORD is required}
+      - DATABASE_DBNAME=${POSTGRES_DB:-sub2api}
+      - DATABASE_SSLMODE=disable
+
+      # Redis Configuration - 使用外部 Redis
+      - REDIS_HOST=${REDIS_HOST}
+      - REDIS_PORT=${REDIS_PORT:-6379}
+      - REDIS_PASSWORD=${REDIS_PASSWORD}
+      - REDIS_DB=${REDIS_DB:-0}
+
+      # Admin Account
+      - ADMIN_EMAIL=${ADMIN_EMAIL:-admin@sub2api.local}
+      - ADMIN_PASSWORD=${ADMIN_PASSWORD:-}
+
+      # JWT Configuration
+      - JWT_SECRET=${JWT_SECRET:-}
+      - JWT_EXPIRE_HOUR=${JWT_EXPIRE_HOUR:-24}
+
+      # Timezone
+      - TZ=${TZ:-Asia/Shanghai}
+
+      # Gemini OAuth (可选)
+      - GEMINI_OAUTH_CLIENT_ID=${GEMINI_OAUTH_CLIENT_ID:-}
+      - GEMINI_OAUTH_CLIENT_SECRET=${GEMINI_OAUTH_CLIENT_SECRET:-}
+      - GEMINI_OAUTH_SCOPES=${GEMINI_OAUTH_SCOPES:-}
+      - GEMINI_QUOTA_POLICY=${GEMINI_QUOTA_POLICY:-}
+    depends_on:
+      postgres:
+        condition: service_healthy
+    # 使用 host 网络模式以访问宿主机上的 1Panel Redis
+    # 或者可以使用 extra_hosts 添加到 1Panel 网络
+    network_mode: bridge
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 30s
+
+  # ===========================================================================
+  # PostgreSQL Database
+  # ===========================================================================
+  postgres:
+    image: postgres:18-alpine
+    container_name: sub2api-postgres
+    restart: unless-stopped
+    ulimits:
+      nofile:
+        soft: 100000
+        hard: 100000
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    environment:
+      - POSTGRES_USER=${POSTGRES_USER:-sub2api}
+      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:?POSTGRES_PASSWORD is required}
+      - POSTGRES_DB=${POSTGRES_DB:-sub2api}
+      - TZ=${TZ:-Asia/Shanghai}
+    network_mode: bridge
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-sub2api} -d ${POSTGRES_DB:-sub2api}"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+      start_period: 10s
+
+# =============================================================================
+# Volumes
+# =============================================================================
+volumes:
+  sub2api_data:
+    driver: local
+  postgres_data:
+    driver: local