servers_v2 差距分析与优化建议（历史归档快照）
Status
Superseded
Date
2026-03-23
Superseded By
docs/architecture/migration-readiness.mddocs/architecture/service-catalog.mddocs/architecture/http-entrypoints.mddocs/services/docs/specs/recon/2026-04-22-recon-service-migration.mddocs/specs/worker-health/2026-04-22-worker-health-and-settlement-hardening.md
Important Note
This document is retained as a point-in-time historical analysis only.
It predates:
- the documented
middle_servermigration posture - the extracted
recon_serviceandrecon_worker - the committed
servers_v2/docker-compose.ymllocal stack - the worker-health and settlement hardening work
Do not use this file as the current migration source of truth. Use the superseding documents above instead.
原始分析日期： 2026-03-23 原始范围： 对比当时的
servers_v2/与servers/，识别功能差距和优化机会。
1. 服务映射总览
| v1 服务 | 端口 | v2 服务 | 端口 | 迁移状态 |
|---|---|---|---|---|
web_server | 8002 | player_service + gateway 路由 | 8002/8080 | 已完成 — player_service 负责认证/资料/消息；gateway 将财务/游戏/记录路由到领域服务 |
admin_server | 8001 | admin_service | 8001 | 大部分完成 — 核心 CRUD、统计、玩家管理、风控、安全配置、活动/优惠券管理均已实现，仅个别能力待确认 |
game_server | 8000 | game_service | 8000 | 接近完成 — 7 个供应商回调已实现；SBO 下游未注册；缺少游戏同步工具 |
agent_server | 8003 | agent_service | 8003 | 已完成 — 完全对等 |
wallet_server | 8004 | wallet_service + rolling_service + promotion_service | 8004/8005/8006 | 已扩展 — 拆分为 3 个领域服务并有改进 |
middle_server | 8005 | （不替换） | — | 不在范围内 |
sms_server | 8006 | rgb_contracts.infra.sms（共享库 + 外部 sms_url 调用） | — | 部分迁移 — 共享库已有可运行的 SmsService + CoolSMS，但实际调用仍走外部 sms_url HTTP 服务 |
| — | — | gateway | 8080 | 新增 — JWT 认证、限流、路由转发、响应翻译 |
关键架构变化：
- v2 新增 gateway 处理所有玩家端流量并路由到领域服务
- v1 的单体
web_server被拆分：认证 →player_service，财务 →wallet_service，游戏 →game_service，记录 → 多个服务 - Gateway 已有完整的路由映射（详见
gateway/CLAUDE.md路由表） - TRON 集成已有意弃用，改用 Plisio（见
servers_v2/CLAUDE.md）
2. 各服务功能差距
2.1 Player Service + Gateway（替代 web_server）
v1 web_server 是一个包含约 59 个端点的单体。v2 中拆分为：
player_service（约 24 个端点）：认证、资料、消息、公共接口wallet_service：财务操作（充值、提现、转账）game_service：游戏列表、启动、供应商列表promotion_service：记录、使用优惠券、活动
gateway（player_routes.py，704 行）已将所有 v1 路径映射到 v2 领域服务目标端点。路由映射已完成。
剩余缺口：Crypto Deposit 闭环 — v2 相比 v1 存在部分回退
v1 现状： wallet_server 的 deposit.py 在创建订单时已调用 Plisio API 并拿到了真实的 wallet_hash（链上地址）（见 deposit.py:659/673），回调也已实现（deposit.py:85）。但 web_url（支付页面链接）被注释置空（deposit.py:671），所以 v1 有"地址分配 + callback"闭环雏形，仅 web_url 未打通。
v2 现状： wallet_service 的 queries.py 有 deposit/gate/create 流程骨架，gateway 路由已映射，Plisio callback（plisio.py:207）和 manual agree（plisio.py:394）也已实现。但创建订单时 wallet_address 和 web_url 均为空字符串占位（queries.py:514），未调用 Plisio API。
结论： v2 在 crypto deposit 上相比 v1 存在部分回退 — v1 至少能拿到链上地址，v2 连地址也还是占位。需要在 deposit/gate/create 流程中集成 Plisio invoice API 调用。
2.2 Admin Service（替代 admin_server）
v2 admin_service 有约 228 个端点，分布在 12 个路由文件中（从 v1 的 92 个路由文件、约 360 个端点整合而来）。这种整合是有意为之 — v2 使用更少但更大的路由文件，组织更清晰。
统计功能 — 已完成
v2 admin_service/app/api/routes/stats.py 有 19 个端点，覆盖 admin/agent/provider/player/sports/deposit/withdraw/rebate/cashback/lossback/coupon/首充 统计。
v1 中的 /stats/online 和 /stats/admin/home 已合并到 /stats/top 端点中，该端点返回仪表盘汇总数据和 online_players（见 stats.py:90，通过 ping_ts 查询近 5 分钟活跃玩家数）。
可能仍缺少的统计端点（1-2 个）：
/stats/recalculate//stats/fix— 统计数据修复工具- 体育子统计：
/sports/branch、/sports/market、/sports/parlay（如业务不再需要则可忽略）
玩家管理 — 已完成
以下能力均已在 v2 中实现：
| 功能 | v2 位置 | 状态 |
|---|---|---|
| 玩家标签 CRUD | player.py:327 — POST /players/{id}/tags | ✅ |
| 玩家分组管理 | player.py:713 — GET/POST /players/groups | ✅ |
| 玩家 USDT 地址管理 | player.py:691 — PATCH /players/{id}/usdt-addresses | ✅ |
| 玩家注册列表 | player.py:813 — GET /players/registrations | ✅ |
| Coin deposit init/details/agree | player_finance.py:318/406/429 | ✅ |
| 风控分析（重复 IP/多账号） | meta.py:139 — POST /analyzer | ✅ |
仍缺失的玩家管理端点（约 3 个）：
- 玩家等级域名操作（domain/edit、set_primary）
- 玩家注册审核（audit、tag_players）
活动/优惠券管理 — 大部分已完成
以下能力已在 v2 中实现：
| 功能 | v2 位置 | 状态 |
|---|---|---|
| 优惠券搜索 | promotion.py:571 — POST /coupon/search | ✅ |
| 优惠券管理员发送日志 | promotion.py:660 — POST /coupon/admin/logs | ✅ |
| 优惠券玩家使用日志 | promotion.py:713 — POST /coupon/player/logs | ✅ |
| 优惠券发送 | promotion.py:763 — POST /coupon/send | ✅ |
| 优惠券回收 | promotion.py:316 — POST /coupon/recycle | ✅ |
| 活动修改（PUT） | promotion.py:954 | ✅ |
| 活动删除（DELETE） | promotion.py:984 | ✅ |
| Deposit/Register/Attendance event 编辑 | promotion.py:1044/1116/1199 | ✅ |
待确认： Excel 批量导入/导出（优惠券模板 Excel 批量发送）
安全与配置 — 已完成
| 功能 | v2 位置 | 状态 |
|---|---|---|
| 封禁 PUT/DELETE | system.py:161/191 | ✅ |
| IP 黑名单 CRUD | system.py:208/215/236/263 | ✅ |
| Banner PUT/DELETE | system.py:402/426 | ✅ |
| Lossback 配置 PUT/DELETE | finance_config.py:189/208 | ✅ |
待确认： 财务维护（bank/deposit/withdraw 配置编辑）、GGR 统计初始化/重算
基础设施 — 已完成
| 功能 | v2 位置 | 状态 |
|---|---|---|
WebSocket（/ws、/ws/sync） | meta.py:309，含 top_info 定时推送 | ✅ |
| 风控分析器 | meta.py:139 — POST /analyzer | ✅ |
| Vera IP 检查 | system.py:602 — POST /vera | ✅ |
| Downloads CRUD | system.py:521/528/549/585 | ✅ |
OpenAPI /openapi.json | FastAPI 默认生成，gateway 已放行（auth.py:46） | ✅ |
| 自定义 meta/schema.yaml 导出 | v1 有 meta.py:159（自定义 YAML 元数据导出），v2 未迁移 | 缺失（低优先级） |
2.3 Game Service（替代 game_server）
供应商回调 — 7 个已完成，SBO 下游未注册
| 供应商 | v1 | v2 | 状态 |
|---|---|---|---|
| BTI | bti_callback.py | bti_callback.py | ✅ |
| BT1 | bt1_callback.py | bt1_callback.py | ✅ |
| HO | ho_callback.py | ho_callback.py | ✅ |
| MG | mg_callback.py | mg_callback.py | ✅ |
| WC | wc_callback.py | wc_callback.py | ✅ |
| Digitain | digitain_callback.py | digitain_callback.py | ✅ |
| S+ | splus_callback.py | splus_callback.py | ✅ |
| SBO | 无独立回调文件 | 无独立回调文件 | ⚠️ gateway 有 /sbo/* 入口（provider_routes.py:106），但 game_service 未注册任何 /sbo 路由（api.py:18），请求会 404 |
SBO 现状： Gateway 会将
/sbo/*请求代理到 game_service，但 game_service 的路由注册中没有/sboprefix（见api.py:18），实际请求到达后无对应 handler。需要确认 SBO 是否仍在使用——如果是，需在 game_service 中添加 sbo_callback 路由。
缺失的工具端点 — 低优先级
| v1 端点 | 用途 | v2 状态 |
|---|---|---|
POST /games_sync/wc | 从供应商 API 同步 WC 游戏列表 | 缺失 |
POST /games_sync/mg | 从供应商 API 同步 MG 游戏列表 | 缺失 |
POST /wc/transaction_details | 查询 WC 交易详情 | 缺失 |
POST /mg/transaction_details | 查询 MG 交易详情 | 缺失 |
GET /mg_games | 单独列出 MG 游戏 | 缺失 |
这些是管理/维护工具，非玩家端关键功能。可能是有意省略。
2.4 Agent Service（替代 agent_server）— 已完成
完全功能对等。 所有 40+ 个端点已迁移，仅命名规范化（camelCase → kebab-case）。
唯一显著差异：POST /forget（密码重置）在 v2 中返回 501 Not Implemented。
2.5 Wallet / Rolling / Promotion Services（替代 wallet_server）
v1 wallet_server 已拆分为 3 个领域服务。所有核心功能均已实现，且有显著改进：
| 能力 | v1 | v2 |
|---|---|---|
| 单一资金写入者 | 部分（wallet_server） | 强制执行（仅 wallet_service 修改余额） |
| 流水逻辑 | 嵌入 wallet_server | 独立 rolling_service + FIFO 引擎 |
| 活动结算 | 混在 wallet_server | 独立 promotion_service + saga 模式 |
| 事件持久化 | 无 | Outbox + inbox 模式 + 幂等性 |
| 可测试性 | I/O 和逻辑混合 | 纯函数 分离（wallet_ops, rolling_ops, settlement_calc） |
| 跨服务安全 | 直接写数据库 | 幂等键 + 重试 |
熔断器现状：
admin_service→wallet_service/rolling_service：有完整熔断器（_CircuitBreaker）game_service→wallet_service：有完整熔断器promotion_service→wallet_service：无熔断器，仅薄封装rolling_service→wallet_service：无熔断器，仅薄封装
2.6 SMS Server → 共享库（部分迁移）
v1 sms_server 的迁移情况：
rgb_contracts.infra.sms共享库已有可运行的SmsService（sms.py:38），CoolSMS 发送逻辑已完整实现（sms.py:165，含 HMAC-SHA256 签名）- 但 v2 中
player_service和agent_service实际调用的是send_sms(sms_url, ...)（sms.py:212），本质上仍是往外部短信网关发 HTTP 请求（见player.py:345、auth.py:369） - 运行形态仍依赖外部 sms_url 服务，并未完全切换为纯库模式
GS 供应商： v1 的
gs.py是空文件，gs_utils.py仅有一个签名工具函数。v1 也未见 GS 的完整实现，因此不算迁移差距。
3. 确认缺失的功能差距
以下是经过逐文件验证确认缺失的功能：
高优先级
| 差距 | 说明 |
|---|---|
| Docker Compose | v2 无 docker-compose 部署配置 |
| Crypto deposit 地址分配 | v1 已调用 Plisio API 拿到 wallet_hash，v2 仍是占位空字符串（部分回退） |
| SBO 下游路由 | gateway 有 /sbo/* 入口，但 game_service 未注册 /sbo handler（如 SBO 仍在使用） |
中优先级
| 差距 | 说明 |
|---|---|
| promotion_service/rolling_service 熔断器 | 两个服务的 wallet_client 无熔断机制 |
| 玩家等级域名操作 | domain/edit、set_primary 约 2-3 个端点 |
| 玩家注册审核 | audit、tag_players 约 2 个端点 |
| SMS 调用模式 | 共享库已就绪但实际仍走外部 sms_url，未切换为纯库模式 |
| Cloudflare R2 | 文件上传/存储未实现 |
低优先级
| 差距 | 说明 |
|---|---|
| 统计修复工具 | recalculate/fix 端点 |
| 体育子统计 | sports/branch、market、parlay |
| 游戏同步工具 | WC/MG games_sync、transaction_details |
| Agent 密码重置 | POST /forget 返回 501 |
| 自定义 meta/schema.yaml 导出 | v1 有自定义 YAML 元数据端点，v2 未迁移（标准 /openapi.json 已有） |
| TRON 占位代码 | 应清理以减少混淆 |
| 钉钉通知集成 | 引用存在但未完整集成 |
| RocketChat | 未实现（v1 也很少使用） |
待确认（非已证实差距）
| 项目 | 说明 |
|---|---|
| 优惠券 Excel 批量导入/导出 | 核心优惠券功能已全部实现，Excel 支持待确认 |
| 财务维护配置 | bank/deposit/withdraw 配置编辑待确认 |
| GGR 统计初始化/重算 | 待确认 |
| 消息定时发送 | 待确认是否已覆盖 |
4. 架构现状与已知技术债
4.1 数据 ownership 未隔离（已记录在 CLAUDE.md）
所有服务共享一个 PostgreSQL 数据库，通过 rgb_db 共享 ORM：
| 服务 | 对 Player 表的访问 | 严重程度 |
|---|---|---|
| wallet_service | SELECT FOR UPDATE + UPDATE | 高 — 直接写耦合 |
| promotion_service | SELECT（text SQL） | 中 — 读耦合 |
| game_service | SELECT（ORM import） | 中 — 读耦合 |
| rolling_service | SELECT（ORM import） | 中 — 读耦合 |
| player_service | Owner | OK |
长期方向（见 servers_v2/CLAUDE.md）：wallet_service 的写操作应改为通过 player_service internal API，或将余额列拆到 wallet 自有表。
4.2 共享 ORM 耦合
所有服务 import from rgb_db.models.main，形成编译时耦合。给 Player 表加一列就需要重新部署所有服务。
建议：
- 每个服务应为自己 own 的表定义独立的 SQLAlchemy 模型
- 对其他服务数据的只读访问应使用 raw SQL 或 HTTP API
- 这是渐进式迁移，非阻塞问题
5. 优化建议
5.1 高优先级
5.1.1 创建 v2 Docker Compose
问题： 无部署配置。服务必须逐个用 uv run uvicorn 启动。
建议： 创建 servers_v2/docker-compose.yml，包含：
- 全部 8 个服务 + PostgreSQL + Redis
- 正确的网络配置（内部服务网格）
- 每个服务的健康检查
- 本地开发的 volume 挂载
- 端口映射对应
servers_v2/CLAUDE.md规范
5.1.2 恢复 Crypto Deposit 地址分配
问题： v1 wallet_server 在 deposit/gate/create 时已调用 Plisio API 拿到 wallet_hash（deposit.py:659/673），v2 的同一流程仅返回空字符串占位（queries.py:514），属于功能回退。
建议： 将 v1 的 Plisio create_order_by_coin 调用逻辑迁移到 v2 wallet_service 的 deposit/gate/create 流程中，回填 wallet_address 到 coin_transaction 表。
5.2 中优先级
5.2.1 熔断器标准化
问题： admin_service 和 game_service 的 wallet_client 有完整熔断器。promotion_service 和 rolling_service 的 wallet_client 仅是薄封装，无熔断机制。
建议： 将熔断器提取为 rgb_contracts.infra.circuit_breaker 共享模块，应用到 promotion_service 和 rolling_service。
5.2.2 SBO 路由确认与实现
问题： Gateway 代理 /sbo/* 到 game_service，但 game_service 未注册 /sbo 路由。
建议： 确认 SBO 是否仍在使用。如果是，在 game_service 中添加 sbo_callback.py 并注册到 api.py。
5.2.3 Admin Service 后台任务提取
问题： admin_service 运行 12+ 个后台任务，形成单体式定时任务运行器。
建议： 考虑将定时任务提取为独立的 worker 进程或采用任务队列。
5.2.4 可观测性
问题： 跨服务请求追踪缺少 correlation ID。健康检查模式不统一。
建议：
- 扩展
/health+/ready到所有服务 - 实现
X-Request-IDheader 传播 - 添加带
request_id上下文的结构化日志
5.3 低优先级
5.3.1 集成测试覆盖
admin_service和agent_service无集成测试- 无跨服务 E2E 测试
5.3.2 清理 TRON 占位代码
admin_service/app/tasks/tron_tasks.py 包含永远不会实现的占位代码，建议删除。
5.3.3 事件 Schema 版本控制
rgb_contracts 中的事件 schema 没有版本字段，建议在 DomainEvent 基类中添加。
5.3.4 配置管理
每个服务独立管理 .env，生产环境建议使用 docker-compose 环境变量或 Vault。
6. 优先级路线图
第一阶段：部署就绪（高优先级）
- 创建 v2 docker-compose，包含全部 8 个服务
- 恢复 crypto deposit 地址分配（迁移 v1 Plisio API 调用到 v2）
- 确认 SBO 是否仍在使用，如是则实现下游路由
- 清理 TRON 占位代码
第二阶段：功能补全（中优先级）
- 补全玩家管理缺口（等级域名操作、注册审核，约 5 个端点）
- 优惠券 Excel 批量导入/导出（如业务需要）
- 实现 agent
POST /forget密码重置 - 补全游戏同步端点（WC、MG — 如仍需要）
第三阶段：架构优化（中优先级）
- 标准化 promotion_service 和 rolling_service 的熔断器
- 增加健康检查和可观测性（correlation ID、结构化日志）
- 将 admin_service 后台任务提取为独立 worker
- 添加 Cloudflare R2 或等效方案用于文件上传（如需要）
第四阶段：长期 DDD（低优先级）
- 按服务隔离数据库 schema（从 wallet_service 开始）
- 共享 ORM 解耦（每服务独立模型）
- admin/agent 服务集成测试覆盖
- 跨服务 E2E 测试套件
- 事件 schema 版本控制