349d783fd1
- Remove old review reports (keep latest only) - Move docs/ to deploy/docs-backup/ - Move performance-testing/ to deploy/ - Clean up test output files - Organize root directory
469 lines
12 KiB
Markdown
469 lines
12 KiB
Markdown
# Sub2API 系统优化方案
|
||
|
||
> 版本: v1.0
|
||
> 日期: 2026-03-26
|
||
> 目标: 完善 Sub2API 功能、提升用户体验、国际化适配
|
||
|
||
---
|
||
|
||
## 一、问题汇总与优先级
|
||
|
||
| 序号 | 问题 | 优先级 | 状态 | 备注 |
|
||
|-----|------|--------|------|------|
|
||
| 1 | 部署问题（.installed锁文件 + sslmode） | P0 | ✅ 已修复 | 之前测试时发现 |
|
||
| 2 | 缺少性能测试 | P0 | ✅ 已完成 | 已添加基准测试 |
|
||
| 3 | 运维文档缺失 | P1 | 待完善 | 需要运维手册 |
|
||
| 4 | 用户管理简单（仅邮箱注册） | P1 | 待增强 | 需社交登录 |
|
||
| 5 | 用户端UI不够友好 | P1 | 待优化 | 需要重新设计 |
|
||
| 6 | 支持模型数量少 | P1 | 待增加 | 需支持国产模型 |
|
||
| 7 | 无在线客服/知识库 | P2 | 待实现 | 客服模块 |
|
||
| 8 | 无Token分享/售卖功能 | P2 | 待实现 | 交易平台 |
|
||
| 9 | 上游账号自动验证 | P1 | 待确认 | 需要实现 |
|
||
| 10 | 激活码安全漏洞 | P0 | ✅ 已修复 | 已验证绑定 |
|
||
| 11 | 支付/钱包功能不完整 | P1 | 待完善 | 需对接Sub2ApiPay |
|
||
| 12 | 国际化不足 | P1 | 待完善 | 需多语言支持 |
|
||
| 13 | 运维自动化缺失 | P1 | 待实现 | 监控告警 |
|
||
|
||
---
|
||
|
||
## 二、详细优化方案
|
||
|
||
### 2.1 用户管理增强 (P1)
|
||
|
||
#### 2.1.1 当前状态
|
||
- 仅支持邮箱注册
|
||
- 无社交登录
|
||
|
||
#### 2.1.2 优化方案
|
||
```
|
||
新增功能:
|
||
├── 社交登录支持
|
||
│ ├── OAuth 2.0 集成
|
||
│ │ ├── GitHub 登录
|
||
│ │ ├── Google 登录
|
||
│ │ ├── Discord 登录 (适合社区)
|
||
│ │ └── Telegram 登录 (适合国际用户)
|
||
│ └── 微信/QQ 登录 (国内)
|
||
├── 用户分组/角色
|
||
│ ├── 普通用户 (user)
|
||
│ ├── VIP 用户 (vip)
|
||
│ └── 代理商/分销商 (agent)
|
||
└── 用户额度管理
|
||
├── 免费额度 (试用)
|
||
├── 充值额度 (余额)
|
||
└── 订阅额度 (套餐)
|
||
```
|
||
|
||
#### 2.1.3 实现建议
|
||
- 后端: 在 `backend/internal/service/auth_service.go` 添加 OAuth 处理
|
||
- 前端: 使用 vue-auth 的第三方登录组件
|
||
- 数据库: 新增 `user_auth_methods` 表
|
||
|
||
---
|
||
|
||
### 2.2 用户端 UI 优化 (P1)
|
||
|
||
#### 2.2.1 当前问题
|
||
- UI 偏技术化
|
||
- 交互不够直观
|
||
- 移动端适配不完善
|
||
|
||
#### 2.2.2 优化方案
|
||
```
|
||
用户端重构:
|
||
├── 仪表盘可视化
|
||
│ ├── 余额/额度展示
|
||
│ ├── 使用图表
|
||
│ └── 快速操作入口
|
||
├── API Key 管理
|
||
│ ├── 密钥复制 (一键复制)
|
||
│ ├── 使用统计图表
|
||
│ └── 密钥有效期管理
|
||
├── 充值中心
|
||
│ ├── 多种支付方式
|
||
│ ├── 套餐选择
|
||
│ └── 充值记录
|
||
└── 移动端适配
|
||
├── 响应式布局优化
|
||
├── 触摸交互优化
|
||
└── PWA 支持
|
||
```
|
||
|
||
#### 2.2.3 实现建议
|
||
- 引入 UI 组件库 (如 Element Plus / Naive UI)
|
||
- 重构前端目录结构，将 admin 和 user 端分离
|
||
- 添加数据可视化 (ECharts / Chart.js)
|
||
|
||
---
|
||
|
||
### 2.3 模型支持扩展 (P1)
|
||
|
||
#### 2.3.1 当前支持
|
||
- OpenAI (GPT系列)
|
||
- Anthropic (Claude系列)
|
||
- Google Gemini
|
||
- AWS Bedrock
|
||
- 自定义 Upstream
|
||
|
||
#### 2.3.2 待支持模型
|
||
```
|
||
国产模型支持:
|
||
├── 百度文心一言 (ernie-bot)
|
||
├── 阿里通义千问 (qwen)
|
||
├── 科大讯飞星火 (spark)
|
||
├── 腾讯混元 (hunyuan)
|
||
├── 字节豆包 (doubao)
|
||
├── MiniMax (abab)
|
||
└── DeepSeek (deepseek)
|
||
|
||
其他模型:
|
||
├── Cohere
|
||
├── Mistral
|
||
└── AI21
|
||
```
|
||
|
||
#### 2.3.3 实现建议
|
||
- 在 `backend/internal/pkg/` 添加新的 provider 适配器
|
||
- 参考现有 `openai_client.go` 结构
|
||
- 更新前端模型选择下拉框
|
||
|
||
---
|
||
|
||
### 2.4 运维文档与搜索 (P1)
|
||
|
||
#### 2.4.1 当前状态
|
||
- 文档分散
|
||
- 无搜索功能
|
||
|
||
#### 2.4.2 优化方案
|
||
```
|
||
运维文档系统:
|
||
├── 文档中心
|
||
│ ├── 安装部署文档
|
||
│ ├── 运维手册
|
||
│ ├── API 文档
|
||
│ └── 常见问题 FAQ
|
||
├── 文档管理
|
||
│ ├── Markdown 格式
|
||
│ ├── 版本控制
|
||
│ └── 分类标签
|
||
└── 搜索功能
|
||
├── 全文搜索
|
||
└── 关键词高亮
|
||
```
|
||
|
||
#### 2.4.3 实现建议
|
||
- 使用 VitePress 或 Docusaurus 构建文档站点
|
||
- 集成 Algolia DocSearch 或本地搜索
|
||
- 文档存放: `docs/`
|
||
|
||
---
|
||
|
||
### 2.5 国际化 (I18n) (P1)
|
||
|
||
#### 2.5.1 当前支持
|
||
- 英文
|
||
- 简体中文
|
||
|
||
#### 2.5.2 待支持语言
|
||
```
|
||
目标语言:
|
||
├── 东南亚
|
||
│ ├── 印尼语 (id)
|
||
│ ├── 越南语 (vi)
|
||
│ ├── 泰语 (th)
|
||
│ ├── 马来语 (ms)
|
||
│ └── 菲律宾语 (tl)
|
||
├── 阿拉伯
|
||
│ ├── 阿拉伯语 (ar)
|
||
│ └── 希伯来语 (he)
|
||
├── 非洲
|
||
│ ├── 斯瓦希里语 (sw)
|
||
│ └── 祖鲁语 (zu)
|
||
└── 南亚
|
||
├── 印地语 (hi)
|
||
└── 乌尔都语 (ur)
|
||
```
|
||
|
||
#### 2.5.3 实现建议
|
||
- 使用 vue-i18n
|
||
- 创建语言文件: `frontend/src/locales/`
|
||
- RTL (从右向左) 布局适配阿拉伯语
|
||
- 数字/日期/货币本地化
|
||
|
||
---
|
||
|
||
### 2.6 在线客服与知识库 (P2)
|
||
|
||
#### 2.6.1 方案设计
|
||
```
|
||
客服系统:
|
||
├── 在线聊天
|
||
│ ├── WebSocket 实时通讯
|
||
│ ├── 客服机器人 (AI)
|
||
│ └── 工单系统
|
||
├── 知识库
|
||
│ ├── 自动回复
|
||
│ ├── 搜索建议
|
||
│ └── 文档推荐
|
||
└── 反馈系统
|
||
├── 问题反馈
|
||
└── 功能建议
|
||
```
|
||
|
||
#### 2.6.2 实现建议
|
||
- 集成开源客服系统 (如 Chatwoot / Rocket.Chat)
|
||
- 或自建轻量级客服模块
|
||
- 知识库可对接 AI 进行智能问答
|
||
|
||
---
|
||
|
||
### 2.7 Token 交易平台 (P2)
|
||
|
||
#### 2.7.1 方案设计
|
||
```
|
||
Token 交易功能:
|
||
├── 出售功能
|
||
│ ├── 设置价格
|
||
│ ├── 设置有效期限
|
||
│ └── 上架管理
|
||
├── 求购功能
|
||
│ ├── 发布需求
|
||
│ └── 价格协商
|
||
├── 交易保障
|
||
│ ├── 托管交易
|
||
│ └── 争议处理
|
||
└── 交易记录
|
||
├── 出售记录
|
||
└── 购买记录
|
||
```
|
||
|
||
#### 2.7.2 实现建议
|
||
- 作为独立模块或插件
|
||
- 对接已有支付系统 (Sub2ApiPay)
|
||
- 需要考虑安全合规
|
||
|
||
---
|
||
|
||
### 2.8 上游账号自动验证 (P1)
|
||
|
||
#### 2.8.1 当前状态
|
||
- 手动验证账号有效性
|
||
|
||
#### 2.8.2 优化方案
|
||
```
|
||
自动验证功能:
|
||
├── 定时检测
|
||
│ ├── 检测频率配置
|
||
│ ├── 验证所有账号
|
||
│ └── 只检测活跃账号
|
||
├── 验证方式
|
||
│ ├── API 调用测试
|
||
│ ├── 余额查询
|
||
│ └── 有效性检查
|
||
├── 状态更新
|
||
│ ├── 有效 → 正常
|
||
│ ├── 无效 → 异常
|
||
│ └── 过期 → 过期
|
||
└── 告警通知
|
||
├── 账号异常通知
|
||
└── 批量异常告警
|
||
```
|
||
|
||
#### 2.8.3 实现建议
|
||
- 在 `backend/internal/service/` 添加账号验证服务
|
||
- 使用 cron job 定时执行
|
||
- 通过 WebSocket 或邮件通知管理员
|
||
|
||
---
|
||
|
||
### 2.9 支付与钱包 (P1)
|
||
|
||
#### 2.9.1 当前状态
|
||
- Sub2ApiPay 为独立项目
|
||
- 集成度不够
|
||
|
||
#### 2.9.2 优化方案
|
||
```
|
||
钱包功能:
|
||
├── 充值
|
||
│ ├── 多种支付方式 (支付宝/微信/Stripe)
|
||
│ ├── 充值优惠
|
||
│ └── 充值记录
|
||
├── 消费
|
||
│ ├── API 调用扣费
|
||
│ ├── 订阅套餐
|
||
│ └── 消费明细
|
||
├── 提现
|
||
│ ├── 提现申请
|
||
│ ├── 审核流程
|
||
│ └── 到账通知
|
||
├── 交易规则
|
||
│ ├── 最低提现额度
|
||
│ ├── 提现手续费
|
||
│ └── 审核周期
|
||
└── 分销/返利
|
||
├── 推广佣金
|
||
└── 下级消费分成
|
||
```
|
||
|
||
#### 2.9.3 实现建议
|
||
- 深入集成 Sub2ApiPay
|
||
- 参考 Stripe Connect 实现分账
|
||
- 钱包数据库设计需要考虑事务安全
|
||
|
||
---
|
||
|
||
### 2.10 运维自动化 (P1)
|
||
|
||
#### 2.10.1 当前状态
|
||
- 缺乏监控告警
|
||
|
||
#### 2.10.2 优化方案
|
||
```
|
||
运维系统:
|
||
├── 监控
|
||
│ ├── 服务健康检查
|
||
│ ├── 资源使用监控
|
||
│ │ ├── CPU / 内存
|
||
│ │ ├── 磁盘 I/O
|
||
│ │ └── 网络流量
|
||
│ ├── 业务指标监控
|
||
│ │ ├── QPS / 延迟
|
||
│ │ ├── 错误率
|
||
│ │ └── 在线用户数
|
||
│ └── 自定义指标
|
||
├── 告警
|
||
│ ├── 告警规则配置
|
||
│ ├── 告警通知渠道
|
||
│ │ ├── 邮件
|
||
│ │ ├── 短信
|
||
│ │ ├── Telegram/Discord
|
||
│ │ └── Webhook
|
||
│ └── 告警升级
|
||
├── 日志
|
||
│ ├── 集中日志收集
|
||
│ ├── 日志搜索分析
|
||
│ └── 日志告警
|
||
└── 自动化运维
|
||
├── 定时任务管理
|
||
├── 备份恢复
|
||
└── 自动扩缩容
|
||
```
|
||
|
||
#### 2.10.3 实现建议
|
||
- 集成 Prometheus + Grafana
|
||
- 使用 Loki 进行日志收集
|
||
- 告警使用 Alertmanager
|
||
- 备份使用 pgBackRest
|
||
|
||
---
|
||
|
||
## 三、兼容性考虑
|
||
|
||
### 3.1 与官方 Sub2API 升级兼容
|
||
|
||
```
|
||
兼容策略:
|
||
├── 版本管理
|
||
│ ├── 主版本号对齐
|
||
│ ├── 次版本号兼容
|
||
│ └── 修订版向前兼容
|
||
├── 代码组织
|
||
│ ├── 核心代码保持独立
|
||
│ ├── 定制代码标记清晰
|
||
│ └── 配置外部化
|
||
├── 数据库迁移
|
||
│ ├── 增量迁移
|
||
│ ├── 数据兼容性检查
|
||
│ └── 回滚方案
|
||
└── API 兼容性
|
||
├── REST API 语义不变
|
||
├── 错误码保持兼容
|
||
└── 新字段可选
|
||
```
|
||
|
||
---
|
||
|
||
## 四、实施路线图
|
||
|
||
### Phase 1: 基础优化 (1-2周)
|
||
|
||
| 任务 | 预计工时 | 优先级 |
|
||
|-----|---------|--------|
|
||
| 运维文档完善 | 3天 | P1 |
|
||
| 上游账号自动验证 | 2天 | P1 |
|
||
| 激活码安全增强 | 1天 | P0 |
|
||
| Docker 部署脚本优化 | 2天 | P1 |
|
||
|
||
### Phase 2: 用户体验 (2-4周)
|
||
|
||
| 任务 | 预计工时 | 优先级 |
|
||
|-----|---------|--------|
|
||
| 用户端 UI 重构 | 3周 | P1 |
|
||
| 社交登录集成 | 1周 | P1 |
|
||
| 国际化完善 | 2周 | P1 |
|
||
| 模型支持扩展 | 1周 | P1 |
|
||
|
||
### Phase 3: 商业功能 (4-6周)
|
||
|
||
| 任务 | 预计工时 | 优先级 |
|
||
|-----|---------|--------|
|
||
| 支付/钱包深度集成 | 2周 | P1 |
|
||
| Token 交易平台 | 3周 | P2 |
|
||
| 在线客服系统 | 2周 | P2 |
|
||
| 运维监控部署 | 2周 | P1 |
|
||
|
||
### Phase 4: 高级功能 (持续)
|
||
|
||
| 任务 | 预计工时 | 优先级 |
|
||
|-----|---------|--------|
|
||
| AI 智能客服 | 2周 | P2 |
|
||
| 自动化运维 | 3周 | P1 |
|
||
| 性能优化 | 持续 | P1 |
|
||
|
||
---
|
||
|
||
## 五、技术栈建议
|
||
|
||
| 功能 | 推荐技术 |
|
||
|-----|---------|
|
||
| 前端 UI | Vue 3 + Naive UI / Element Plus |
|
||
| 国际化 | vue-i18n |
|
||
| 文档 | VitePress |
|
||
| 监控 | Prometheus + Grafana |
|
||
| 日志 | Loki + Promtail |
|
||
| 告警 | Alertmanager |
|
||
| 支付 | Sub2ApiPay / Stripe |
|
||
| 客服 | Chatwoot / 自建 |
|
||
| CI/CD | GitHub Actions / GitLab CI |
|
||
|
||
---
|
||
|
||
## 六、风险与挑战
|
||
|
||
| 风险 | 应对方案 |
|
||
|-----|---------|
|
||
| 官方升级冲突 | 保持核心代码独立，定制代码模块化 |
|
||
| 多语言翻译 | 社区贡献 + 机器翻译 + 人工校验 |
|
||
| 支付合规 | 咨询法务，使用正规支付渠道 |
|
||
| 性能瓶颈 | 提前做性能测试，优化数据库 |
|
||
| 安全漏洞 | 定期安全审计，依赖更新 |
|
||
|
||
---
|
||
|
||
## 七、总结
|
||
|
||
本方案覆盖了您提出的所有问题，并提供了系统化的解决思路。建议按照优先级分阶段实施:
|
||
|
||
1. **立即修复**: 运维文档、上游账号验证
|
||
2. **短期目标**: 用户体验、UI优化、国际化
|
||
3. **中期目标**: 支付集成、Token交易
|
||
4. **长期目标**: AI客服、运维自动化
|
||
|
||
需要我针对某个具体模块开始详细设计和实现吗?
|
||
|
||
---
|
||
|
||
*文档版本: v1.0*
|
||
*最后更新: 2026-03-26* |