opc-backup/云超服一体化架构设计方案.md

云超服一体化平台架构设计方案

版本：v0.1（2026-08-23） 定位：在现有全部代码资产基础上，面向「统一身份 · 统一后端 · 多端互通 · 智慧园区」的一体化架构设计。 阅读对象：架构 / 前后端 / 园区端 / 算力相关开发。 关联文档：design/云超服平台/（身份体系与端口权限、全量方案、架构初步设计）、materials/培训计划/课程体系0.1/三端架构设计.md、各代码仓库 README.md。

---

〇、设计原则

1. 一个身份：全平台（桌面端 / Web / 小程序 / 园区大屏）共享一套账号与端口身份，数据全部归属到身份。
2. 一个后端、模块化拆分：业务与身份收敛到后端 server（现 server-core 演进），内部按业务域拆模块，可演进为微服务，消除多后端多账号并存。
3. 专业服务外置：算力引擎（new-api，仅服务、管理/页面自研）、Agent 运行时（智能体桌面应用内）作为专业服务，通过明确 API 与后端协作，不混业务。
4. 算力额度服务端统一管控：架构上预留充值链路，当前流程由服务端统一增减额度，用户端只读展示。
5. 契约可校验：后端出 OpenAPI → 多端前端生成 TS client，消灭手写契约漂移。
6. 迁移渐进：先统一身份 → 再迁业务域 → 再补用户端功能 → 最后升级大屏，全程可回滚。

---

一、设计目标与六条要求映射

#	要求	落地主体	本文档章节
1	全局统一身份系统	核心服务端七端口 RBAC（已有） + 六端登录归一	§三
2	后端集成算力调度、用户管理；运营端迁移 web 课程/活动管理	核心服务端业务域扩展 + new-api 集成	§四
3	多端（小程序 / web业务 / web官网 / admin管理平台 / 智能体桌面 / 大屏）数据互通	统一身份 + 统一后端 + 统一契约	§四.4
4	用户端完整功能：算力/园区入驻/智能体/政策/财务/工商	核心服务端 opc 端口 + 各业务域 router	§五
5	园区端智慧大屏增强，数据由后端园区端管理可换	dpm 数据源改造 + 核心服务端园区数据域	§六
6	大屏真实展示人员、智能体实时消耗（token/流水）	dpm 对接核心服务端 + new-api 实时数据	§六

---

二、总体架构（目标态）

2.1 前端（6 端）

端	定位	代码资产	后端接入
小程序	移动 C 端（OPC AI：测评/政策/报名/算力）	training/miniprogram	gateway · /auth /opc/* /tests/*
web业务	业务 C 端（培训/课程/活动/测评/政策）	training/website/user	gateway
web官网	公开展示站（产品/政策/招生/案例）	web-official（原 PineAgentsWeb）	gateway（公开接口 + 静态内容）
admin管理平台	运营/政务/企业/载体/服务商/投资人管理	console 管理端（operator/government/…端口）	gateway · /admin/*
智能体桌面应用	智能体工作台（Agent OS + Tauri 壳）	agent-desktop（原 PineAgents，console + Tauri）	gateway（/auth /agents）+ 算力服务 → 引擎 /v1
大屏桌面应用	多园区通用大屏（园区账号登录显示本园区）	park-desktop（原 dpm，Tauri）	gateway（/api/park/*，org_id 隔离）

2.2 后端（server · 完整服务群）

后端是一组完整服务构成的服务群，可整体一个进程部署（模块化单体），亦可按需拆成独立微服务（分库 + 网关路由）。模块边界即微服务拆分边界。

应用服务（业务域）

服务	职责	现状基础
核心服务	统一入口（gateway）+ 身份（auth）+ 业务模块（business/agent/task/gov/park/notify/file）	server-core 演进 + training 业务迁移
算力服务	封装 new-api 引擎：令牌/额度/流水聚合、用户算力自助；仅消费 new-api 的服务（relay 与程序化管理 API），管理与页面全部自研	compute_client → new-api

基础设施服务

服务	职责	说明
MQTT 消息服务	实时消息/指令/推送总线	EMQX；大屏（dpm）、桌面端通知、控制指令复用
缓存服务	会话/限流/聚合缓存	Redis；多节点共享额度与状态
数据库服务	主库 + 分库	模块化单体用 SQLite；微服务演进用 MySQL / PostgreSQL

核心服务内部模块（微服务拆分边界）

模块	职责
gateway 网关	统一入口、鉴权校验、路由、契约、跨端限流
auth 身份	七端口 RBAC、select-identity、审计、登录
business 业务	课程/活动/报名/测评/政策申报/入驻/财务/工商
agent 智能体	智能体定义/模板/桌面同步
task 任务生态	任务/服务商/结算/合同/争议/信用
gov 政务	补贴审批、政务三级数据范围
park 园区	园区数据域 + 大屏聚合
notify 通知	通知/消息/推送（可接 bark-notify）
file 文件	上传/媒体/静态托管

new-api 定位：只作为算力引擎服务被算力服务消费（/v1 中继 + 管理 API 程序化调用）；不使用其自带 web 管理页面/用户页面——算力相关的管理全部在 admin管理平台（console）实现，页面风格统一。

2.3 专业服务（外置，不混业务）

服务	职责	边界
算力引擎（new-api）	模型网关 + 额度/令牌 + token 流水/计费	只做模型计量，不做身份；仅服务，无页面暴露
Agent 运行时（智能体桌面应用内）	智能体执行引擎（决策/工具/频道/沙箱）	算力统一走算力服务 → 引擎 /v1

部署形态：算力引擎随后端服务群一同部署（同机/同编排），不做本地推理——全部渠道均为云厂商代理（OpenAI / DeepSeek / 通义千问 / Claude / Gemini 等），无需 GPU 主机。算力服务与引擎同机互通，网络简单、凭据不扩散。代码：code/compute-engine/（new-api，启动命令见其 README.云超服.md）。

退役清单：training server（业务迁后端后退役）、training website/server（mock，已基本废弃）、training website/platform 管理端（迁入 admin管理平台）。

---

三、统一身份系统（要求 1）

3.1 身份中心

沿用核心服务端已有的 七端口 RBAC：users + user_identities（一账号多端口身份）+ roles/permissions/role_permissions + select-identity 切换 + 政务三级数据范围。该机制已成熟（含提权防护、token_version 吊销、require_port 隔离）。

3.2 六端登录归一（同一账号 = 同一身份）

端	登录方式	到核心服务端的映射
智能体桌面应用	账号密码 + select-identity	POST /auth/login（已有）
admin管理平台	账号密码 + RBAC	/auth/login + 运营/政务等端口身份
web业务	手机号 + 验证码	复用 register/phone-login（补手机号登录端点）
小程序	微信 wx.login + getPhoneNumber	新增 wx_openid 绑定字段（users/user_identities），登录即建 opc_member 身份
web官网	公开访问（可选登录）	仅公开接口 + 静态内容
大屏桌面应用	园区账号（carrier 身份）	/auth/login + select-identity → 绑定 org_id

新增能力（核心服务端）：

• users 表补 wx_openid（或经 user_identities 建立微信身份行）；补 /auth/phone-login、/auth/send-code、/auth/wx-login、/auth/wx-phone 端点（迁移自 training server/app/auth.py 的短信与微信流程，合并手机号账号逻辑）。
• 原 training accounts 表迁移：username/phone/wxid/name/avatar/status_label/topics/source → users + opc_profiles（报名画像字段挂到 opc_member 身份，沿用现 opc_profiles 表）。

3.3 数据归属

所有业务数据的唯一归属 = user_id（+ 可选 identity_id 维度）。课程报名、测评结果、算力订单、入驻申请、财务流水、政策申报一律以 user_id 关联，天然实现多端互通（同一人在任意端操作，数据落在同一身份上）。

---

四、统一后端与业务域（要求 2、3）

4.1 核心服务端业务域扩展（数据模型）

在现有 34 张表基础上新增（继承现 models.py 风格）：

新表	关键字段	对应需求
courses	id/title/category/level/chapters(JSON)/syllabus/start_end/venue/quota/price/status/cover	课程实体（迁自 website data/*）
activities	id/type(free·salon·training·park)/title/subtitle/desc/location/host/image/link/start_at/end_at/checkin_at/duration_min/capacity/status/audit_mode/show_capacity	通用活动（迁自 training events）
bookings	id/user_id/target_type(course·activity·park)/target_id/status(applying·approved·attended·absent)/audit_status/note/checkin_at	统一报名（替代 roadshow_registrations + training_enrollments + training bookings）
tests + test_results	id/title/category/questions(JSON)/pass_score；id/user_id/test_id/score/passed/cert_id	测评/考核（引擎迁自 opc_engine.py/policy_engine.py/survey_data.py）
compute_accounts + compute_orders	user_id/balance/token_ref；id/user_id/amount/type(add·deduct·freeze)/reason/operator_id/created_at	算力额度与增减流水
park_admissions	id/opc_id/carrier_id/area/station_count/purpose/status(apply·auditing·approved·settled)/contract_id	园区入驻申请
business_services + business_orders	id/name/fee/agency_id；id/user_id/service_id/status(apply·pending·done)	工商/政务代办
invoices + finance_accounts	id/org_id/amount/type；企业/服务商对公财务	企业/服务商财务
park_org + park_companies + park_members	园区信息/企业名录/人员名单（大屏数据源）	园区端数据管理
policy_applications	id/user_id/policy_id/status	政策申报（补 subsidy_applications 之外的普通政策申报）

迁移自 training 的数据：events → activities、bookings → bookings、tests/policy_logs/plan_logs/survey_logs → tests + test_results（测评结果）、policy_data/plan_data/survey_data → 核心服务端 content_items`(policy 类型) + 引擎服务。

多园区维度：园区相关数据（park_*、园区活动、报名、播放列表）均以 org_id 隔离；园区 = organizations(type=carrier)。详见 §六。

4.2 运营端：web 课程/活动管理迁移（要求 2）

把 training website/platform 的管理功能整体迁入 console 运营端（operator 端口），新增 router rbac_operator 端点（沿用现 /admin 前缀）：

管理能力	现所在（web platform）	迁至端点
课程管理	Schedule/Structures/Cards/Tools（静态内容页）	GET/POST/PUT/DELETE /admin/courses、/admin/courses/{id}/status
活动/排期管理	PineEvents	GET/POST/PUT/DELETE /admin/activities、/admin/activities/{id}/status
报名管理	PineBookings（名单/状态/审核/导出 CSV）	GET /admin/bookings、PATCH /admin/bookings/{id}、POST /admin/bookings/export
测评管理	PineTests	GET /admin/tests、POST /admin/tests、GET /admin/test-results、POST /admin/test-results/export
签到	checkins	POST /admin/checkins（时间闸复用）
运营统计	PineOps	GET /admin/stats/overview（扩展课程/活动/测评/算力维度）

前端：console 新增 Operator/Courses|Activities|Bookings|Tests 页面（复用现有 pineAdmin.jsx 的 useOps hook 模式 + 原子组件），调上述端点。

4.3 算力调度与用户管理（要求 2）

算力服务接入（后端新增 compute_client.py，照抄 server_client.py 的 httpx 转发模式；new-api 仅作引擎被消费，管理/页面全部自研）：

• 平台管理 token：算力服务持有 new-api 管理令牌，作为统一入口（仅程序化调用，不暴露其管理 UI）。
• 建号发 token：用户开通算力时 → POST /api/user 建 new-api 用户（username = 云超服 uid）+ POST /api/token 签发 PAT，映射存 compute_accounts。
• 额度增减（服务端统一，无用户充值）：运营端 POST /admin/compute/orders（add/deduct/freeze）→ 算力服务调 new-api 调整额度 → 写 compute_orders 流水 → 通知用户。当前不暴露任何用户充值接口；架构上预留 POST /api/user/topup 转发能力（new-api 已支持），待支付渠道/合规就绪再启用。
• 用户读端：GET /opc/compute 聚合返回 { 余额（/api/user/self）、本月消耗（/api/data/self）、流水（/api/log/self）}，30s 缓存 + 消耗预警。
• Agent 算力：桌面端 PROVIDER_PINEAGENTS.base_url 指向算力引擎 /v1（环境变量化），登录/换身份时算力服务下发该用户 PAT 注入 provider（require_api_key=False 改为用户级 token）。

用户管理：运营端 POST /admin/users（已有）+ 扩展「开通算力/分配端口/发放公益额度」一体化流程。

4.4 多端数据互通（要求 3）

统一后端 + 统一身份后，六端天然互通。前端统一契约：

• 核心服务端补全 Pydantic 模型 → openapi.json → 生成 TS client（小程序 / web业务 / web官网 / admin管理平台 / 智能体桌面 / 大屏共用）。
• 双端 API_BASE 收敛为构建期注入的单一配置。
• 数据一致性：报名/测评/算力/政策结果以 user_id 为键，多端读写同一后端。

---

五、用户端功能全集（要求 4）

全部落在 OPC 端口（rbac_opc 扩展）+ 关联端口协作。前端：console Opc/ 页面（主）+ 小程序/Web 复用同一组 API。

功能	核心服务端端点	数据/引擎	交互要点
算力管理	GET /opc/compute、GET /opc/compute/usage、GET /opc/compute/orders	compute_client → new-api	只读余额/消耗/流水；额度不足引导联系运营；无充值
园区入驻	POST /opc/park-admission、GET /opc/park-admission	park_admissions	提交入驻申请 → 载体 POST /carrier/admissions/{id}/approve → 签约（复用 contracts）→ settled
智能体	GET /opc/agent（已有）、POST /opc/agent/{id}/chat	agent-desktop（智能体桌面）（算力走 new-api）+ agents 表	一键唤起本机/云端 Agent，消耗计入本用户算力
政策管理	GET /opc/policy（已有）、POST /opc/policy/{id}/match、POST /opc/policy/{id}/apply	content_items(policy) + 匹配引擎（迁自 policy_engine.py）+ policy_applications	政策匹配 → 申报 → 政务三级审批（复用现 subsidy 链路）
财务管理	GET /opc/finance、POST /opc/finance/record（已有）、GET /opc/invoices	finance_records + invoices	OPC 收支 + 发票申请
工商注册/代办	GET /opc/affairs（改造）、POST /opc/business/{service}/apply、GET /opc/business-orders	business_services/business_orders	OPC 提交代办 → 服务商 GET/POST /provider/business-orders 接单办结
课程/测评	GET /opc/courses、POST /opc/courses/{id}/enroll、GET/POST /opc/tests/{id}、POST /opc/tests/{id}/submit	courses/tests/test_results	培训报名 + 测评，结果入 test_results 可二次查看

新增 rbac_opc 端点清单（增量）： /opc/courses、/opc/courses/{id}、/opc/courses/{id}/enroll、/opc/activities、/opc/activities/{id}、/opc/activities/{id}/signup、/opc/bookings（我的报名）、/opc/tests/{id}、/opc/tests/{id}/submit、/opc/compute、/opc/compute/usage、/opc/compute/orders、/opc/park-admission、/opc/business/{service}/apply、/opc/business-orders、/opc/policy/{id}/match、/opc/policy/{id}/apply、/opc/invoices。

新增权限码（seed.py）：action:course.manage、action:activity.manage、action:enrollment.manage、action:test.manage、action:compute.manage、action:admission.manage、action:business.manage、action:park.manage → 挂到 operator|op_super_admin/op_admin/op_customer_service；用户侧 opc_member 只读/申请权限。

---

六、园区端智慧大屏（要求 5、6）

新定位：dpm 是多园区通用的大屏客户端（一套 Tauri + React 代码，任何园区部署即用）。园区账号（carrier 端口身份）登录后，只显示本园区的内容——园区信息 / 企业 / 人员 / 活动 / 媒体轮播 / 真实 token 消耗与流水，全部按 org_id 隔离。

6.1 现状缺口（已核实）

dpm 现为"单园区固定大屏"：数据 100% 来自 sim_engine.py 静态常量 + TOKEN 测算演示（random 波动）；无数据库、无登录、无外部系统对接；/admin 只能管本机媒体/播放列表，不能改园区数据；/wall 企业墙是前端硬编码静态数组。实现"多园区通用 + 真实数据"需三步改造：多租户数据维度 → 园区账号登录 → 真实数据源接入。

6.2 多园区数据维度（org_id 隔离）

• 每个园区 = 核心服务端一个 organizations(type=carrier)（园区即载体）。园区数据域 park_org/park_companies/park_members、活动、报名、播放列表、算力聚合全部以 org_id 隔离。
• 核心服务端 GET /api/park/* 用 carrier 身份 + org_id 数据范围只返回本园区数据（复用现有范围机制 require_port(carrier) + visible_region_ids/org 范围），跨园区越权一律 403。
• 新增表：park_org(org_id PK)、park_companies(org_id, …)、park_members(org_id, …)、park_playlists(org_id, …)（媒体轮播内容归园区）。

6.3 园区账号登录（统一身份）

• 园区账号 = 核心服务端 carrier 端口身份（可含 park_admin 子角色）。dpm 大屏（Tauri 壳内）提供登录入口：POST /auth/login + select-identity → 取 carrier 身份 token → 绑定该园区。
• token 由 dpm 后端安全存储（复用 agent-desktop（智能体桌面） auth_token_store 思路），启动时校验并拉取本园区数据；失效自动跳登录。
• 一套 dpm 代码，换园区即换账号——"所有园区通用，园区账号登录后显示园区自己的内容"。

6.4 园区数据管理（要求 5）

• 核心服务端扩展园区数据域端点：GET/POST/PUT /admin/park、/admin/park/companies、/admin/park/members。
  • 运营端（operator）：可管理所有园区；
  • 载体端（carrier）：只能维护本园区数据（org_id 范围）——"后端园区端实现数据的更换"落地。
• 数据来源：materials/园区数据资料/ 定稿数据按园区导入 park_* 表（不再硬编码）。

6.5 大屏真实数据（要求 6）

dpm 后端新增数据源层，以园区账号 token 拉取本园区数据（替代 sim_engine 模拟部分）：

大屏维度	数据源	接口（org_id 过滤）
园区概况/企业/人员	核心服务端	GET /api/park/data（园区信息 + 企业 + 人员 + 入驻统计）
真实 token 消耗/流水	new-api	本园区用户经 compute_client 聚合 /api/log（按 org 分组），实时 2.2s tick + MQTT opc/dashboard/tick
实时智能体消耗	核心 + new-api	GET /api/park/agents/usage（本园区人员 × 智能体 × token 聚合）
活动/报名/测评统计	核心服务端	GET /api/park/biz（本园区活动/报名/测评）
媒体轮播	dpm 自身	park_playlists（本园区播放列表）

改造要点：

• dpm/backend/app/ 新增 data_source.py：带园区 token 轮询核心服务端聚合端点 + 算力聚合，内存缓存，tick 推进；sim_engine.py 删除随机模拟 token，只保留通用布局骨架。
• 新增 REST：GET /api/agents/usage、GET /api/park/real；前端 useParkSim 接入真实快照。
• /wall 企业墙改为 GET /api/park/companies（本园区，不再硬编码）。
• 实时链路：沿用 REST 轮询(2.2s) + MQTT opc/dashboard/tick + SSE 兜底；token 流水经核心代取（避免 dpm 直连 new-api 凭据扩散）。

6.6 大屏页面增强

DataScreen 增加「人员在线/智能体运行中/实时 token 消耗/分企业 token 排行/今日流水」区块；DigitalTwin 3D 右侧面板绑定本园区真实企业/人员数据；/twin、/screen、/wall 数据全部走后端且按园区隔离。

---

七、数据模型总表（核心服务端目标态）

身份域（已有）：users、user_identities、roles、permissions、role_permissions、regions、sessions、audit_logs、organizations、organization_members Agent/生态（已有）：agents、opc_profiles、tasks、bids、escrows、contracts、disputes、ratings、notifications、messages、opc_tasks、service_providers、service_referrals、roadshows、roadshow_registrations、investment_intents、investor_preferences、training_enrollments 内容/政务（已有）：content_items、system_configs、portal_dashboards、portal_pages、subsidy_applications 新增业务域：courses、activities、bookings、tests、test_results、compute_accounts、compute_orders、park_admissions、business_services、business_orders、invoices、finance_accounts、policy_applications、park_org、park_companies、park_members 外部数据（不落核心库）：new-api 用户/token/日志（经 compute_client 访问）、PineAgents 会话/记忆（本地）、dpm 播放列表/设置（本地 data.json）

迁移对照：training events→activities、bookings→bookings、tests/policy_logs/plan_logs/survey_logs→tests/test_results、policy_data→content_items+policy_applications。

---

八、统一契约与跨服务接口

8.1 契约机制（OpenAPI 生成，消灭手写漂移）

• 单一事实源：核心服务、算力服务全部 router 用 Pydantic 请求/响应模型，自动产出 openapi.json。
• 聚合与生成：gateway 汇总各服务 OpenAPI → 生成 TS client（小程序 / web业务 / web官网 / admin管理平台 / 智能体桌面 / 大屏共用）；接口语义化版本 /api/v1。
• 契约治理：CI 加「契约变更 → 重新生成 → diff」检查，双端锁版本；破坏性变更走新版本而非原地修改。

8.2 服务间接口矩阵

调用方	被调方	接口	协议 / 鉴权
小程序 / web业务 / web官网 / admin管理平台	gateway	/api/v1/*	HTTPS · Bearer 用户 token
大屏桌面（dpm）	gateway	/api/park/*	HTTPS · 园区账号 token（org_id 只返回本园区）
智能体桌面应用	gateway	/auth/* /agents/*	HTTPS · 用户 token
gateway	核心服务	/auth /opc /admin /agent 等	内网 HTTP · 服务账号 token + 透传用户身份
gateway	算力服务	/compute/*	内网 HTTP · 服务账号 token
核心服务	算力服务	/compute/*（额度/聚合）	内网 · 服务账号
算力服务	算力引擎（new-api）	/v1/* + /api/*（管理）	loopback · 管理令牌（程序化）
智能体桌面应用	算力引擎（经算力服务代理）	/v1/*（模型调用）	loopback 代理 · 用户 PAT
核心服务	MQTT 消息服务	主题发布/订阅	内网 · MQTT 凭据
核心服务	缓存服务	key 操作	内网 · 密码
核心服务	数据库服务	SQL	内网 · DSN

8.3 鉴权分层

层	凭据	范围
用户层	六端统一 Authorization: Bearer <用户token>	gateway 校验，按身份/端口
服务层	服务账号 token（环境变量注入，不硬编码）	服务间调用，按服务/权限 scope 隔离
数据层	org_id / region 数据范围（已有机制）	园区/政务数据越权 403

• 算力接口：算力服务 ↔ new-api 走管理 API（建号/发 token/额度调整/日志）；compute_client.py 统一封装，含超时/重试/502 兜底（照 server_client.py）。引擎与服务群同机部署，loopback 互通。
• 大屏数据：dpm → 核心 /api/park/* 经核心代取 new-api 日志（避免 dpm 直连 new-api 凭据扩散）。

8.4 实时通道

通道	用途	出口
MQTT（EMQX）	大屏/桌面实时数据、控制指令、通知	经 gateway WS 出口，内网不直接暴露
SSE	大屏快照回退（现 dpm 已有）	gateway
WebSocket	桌面 Agent 会话、语音	gateway

8.5 通知/消息

业务事件（额度到账 / 入驻审核 / 报名结果 / 测评完成）统一走 notifications（现缺写入端点，补 notifications.create service），支持站内信 + 可接 bark-notify 手机推送。

---

九、迁移与演进路线

阶段	内容	退出条件	涉及
0 · 基座	后端补 Pydantic 模型 + OpenAPI；compute_client 打通 new-api；users 补 wx_openid + 手机号/微信登录端点	六端能连后端登录	server-core、new-api
1 · 身份统一	training accounts 迁移 → users/opc_profiles；六端登录全部走后端；小程序/Web 改 API_BASE	同一账号六端互通	training web/miniprogram、server-core
2 · 业务域迁移	courses/activities/bookings/tests 建表 + rbac_operator 端点 + 数据迁移；web platform 管理迁入 console 运营端	运营端可完整管理课程/活动/报名/测评	server-core、console、training website
3 · 用户端补全	算力管理/园区入驻/政策申报/财务/工商代办 + rbac_opc 端点 + console Opc/* 页面	OPC 用户端六功能可用	server-core、console
4 · 园区大屏	dpm 多租户化（园区账号登录 + org_id 隔离）；data_source 接核心+new-api，替换 sim_engine 模拟；园区数据管理页	大屏真实人员 + 实时 token/流水	dpm、server-core
5 · 收尾	退役 training server、website/server mock、website/platform；README/文档同步	单后端 + 四前端稳定运行	全仓

每阶段独立可交付、可回滚；阶段 1 后数据即以 user_id 归位，阶段 2 后运营单入口。

---

十、风险与依赖

1. 合规：向公众提供生成式 AI 的备案/内容安全/实名/日志留存义务（new-api README 有明确提示）；算力额度发放涉及收费边界，需政策/法务确认。参考 materials/搜集资料/政策汇总.md。
2. 迁移期双写：阶段 1-2 需 training server 与核心服务端双写/一次性迁移脚本，避免丢数据；测评引擎移植需同一组测试用例双端验证（沿用 小程序同步约束.md 思路）。
3. new-api 自研依赖：new-api 是 AGPLv3 开源（One API 的 fork），需确认许可合规与自研维护成本；额度调整用其管理 API，锁定版本。
4. 桌面端离线/断网：不做本地推理，Agent 算力完全依赖云端（new-api → 云厂商渠道）；断网或云厂商不可用时智能体不可用，需明确降级提示、超时与重试策略。
5. 性能：核心服务端承载全业务，SQLite 在并发大时需评估；大屏 2.2s 轮询建议走独立只读副本或缓存（现有 dpm tick 机制可承担）。
6. 品牌未接线：PineAgents console 品牌常量未消费（storage key 仍 qwenpaw_*），统一后需一并收敛。

---

十一、部署拓扑（服务群编排）

11.1 端口清单

服务	端口	暴露范围	说明
gateway 网关	:443（HTTPS）/ :80	公网	TLS 终结、统一入口；WS/WSS 供大屏/桌面
核心服务	:8090	内网	身份 + 业务域 + 园区聚合
算力服务	:8092	内网	额度/令牌/流水聚合，封装 new-api
算力引擎 new-api	:3000	仅内网 loopback	仅服务（relay /v1 + 管理 API），无页面暴露
MQTT 消息服务	:1883 / :8083(WS)	内网（大屏/桌面经网关 WS）	EMQX，实时消息/指令/推送
缓存服务	:6379	内网	Redis，会话/限流/聚合缓存
数据库服务	:3306（MySQL/PG）或 SQLite 文件	内网	模块化单体用 SQLite；微服务演进用 MySQL/PostgreSQL 分库

11.2 依赖与启动顺序

数据库 / Redis / EMQX  ──→  核心服务 + 算力服务  ──→  算力引擎 new-api  ──→  gateway 网关
（先起基础设施）            （业务就绪）           （消费其服务）           （最后对外）

• 算力引擎随后端一起部署（同一 Docker Compose），算力服务经 loopback :3000 调用，无跨网凭据扩散。
• 大屏/桌面端的实时通道（MQTT / SSE / WS）统一经 gateway 出口，内网不直接暴露 EMQX / new-api。

11.3 存储与卷

数据	存放	备份策略
业务库（身份/业务/园区/算力流水）	SQLite data/app.db → MySQL/PG	定时快照 + WAL
缓存/会话	Redis	可重建，无需备份
文件/媒体（上传、大屏播放列表）	uploads/ + park_playlists	对象存储或卷备份
new-api 数据（引擎侧）	卷挂载 /data	随服务群备份

11.4 网络与安全

• 公网仅暴露 gateway；EMQX / Redis / DB / new-api 全部内网，凭据不扩散。
• 服务间调用用服务账号 token（环境变量注入），算力服务 → new-api 用其管理令牌（仅程序化）。
• 出站仅算力引擎需要访问云厂商 API；其余服务禁出站（或白名单）。

---

十二、当前 code 各项目如何工作

每个子项目均为独立仓库（组织 Pine），位于 code/。以下为职责 / 关键文件 / 启动命令 / 工作流。

12.1 server-core — 核心服务端（总后端）

• 职责：身份/平台 API + 培训子应用，对外统一 opc.pinesound.cn。
• 关键文件：dispatcher.py（统一入口，按路径路由 /api/*→培训子应用、其余→平台应用）、app/main.py（身份 + 业务域）、app/training/（培训子应用，独立库 data/opc.db）、app/routers/（auth/opc/admin/government…）。
• 启动：cd code/server-core && uv run uvicorn dispatcher:app --host 0.0.0.0 --port 8090 --reload
• 工作流：前端请求 → dispatcher → /api/* 走培训子应用（报名/测评/政策），/auth /opc /admin 走平台应用（七端口 RBAC / 业务域）。

12.2 compute-engine — 算力引擎（new-api 微服务）

• 职责：OpenAI 兼容 /v1 模型中继 + 额度/令牌/token 流水；仅服务，管理/页面自研。
• 关键文件：main.go（入口）、relay/（模型中继）、controller/（管理 API）、docker-compose.yml；启动说明见 README.云超服.md。
• 启动：cd code/compute-engine && cp .env.example .env && docker compose up -d
• 工作流：智能体/算力服务经 loopback :3000 调用 /v1/*（模型）与 /api/*（管理，程序化）；引擎代理云厂商渠道（OpenAI/DeepSeek/通义千问/Claude/Gemini），不做本地推理。

12.3 agent-desktop — 智能体桌面应用（PineAgents）

• 职责：智能体工作台（Agent OS）：对话、Skills/插件、定时任务、代码模式、多频道。
• 关键文件：src/pineagents/（Python 后端运行时：agents/runtime/governance/sandbox/memory）、console/（React 前端）、console/src-tauri/（Tauri 壳）、src/pineagents/app/routers/auth.py（认证转发到 server-core）。
• 启动：cd code/agent-desktop/console && yarn dev；后端 pineagents app（:8088）。
• 工作流：用户从 console / CLI / 频道发消息 → 后端运行时编排 → 智能体决策（ReAct）→ 工具执行（治理/沙箱）→ 模型调用经 compute-engine /v1 计量。

12.4 park-desktop — 园区大屏桌面应用（dpm）

• 职责：多园区通用大屏：数据大屏、数字孪生、AI/语音助手、媒体轮播、企业墙；园区账号登录只显示本园区。
• 关键文件：src/（React 前端，路由 / /twin /ai /screen /voice /wall）、src-tauri/（桌面壳）、backend/（FastAPI :10085 + MQTT + sim_engine）、app/data_source.py（规划：接核心服务端 + 算力引擎真实数据）。
• 启动：cd code/park-desktop && yarn dev；后端 cd backend && uv run python main.py（:10085）。
• 工作流：大屏经 REST/MQTT/SSE 拉快照 → 园区账号登录（carrier 身份，org_id 隔离）→ 只展示本园区数据；真实 token 消耗经 server-core 代取 compute-engine。

12.5 web-official — 官网展示端（PineAgentsWeb）

• 职责：公开展示站（产品/政策/招生/案例），静态 SPA。
• 关键文件：src/（Vite + React）、vite.config.ts、package.json。
• 启动：cd code/web-official && pnpm install && pnpm run dev
• 工作流：纯展示，公开接口 + 静态内容；可选登录走后端。

12.6 training — 培训前端（小程序 + 网站）

• 职责：C 端培训业务（课程/活动/报名/测评/政策/算力），后端已并入 server-core 培训子应用。
• 关键文件：miniprogram/（Taro 小程序）、website/（Vite React，src/user/ C 端）；API_BASE = https://opc.pinesound.cn。
• 启动：cd code/training/miniprogram && yarn dev:weapp；cd code/training/website && pnpm dev
• 工作流：小程序/网站调 opc.pinesound.cn/api/* → server-core dispatcher → 培训子应用（报名/测评/政策/算力）；与 server-core 身份互认（统一身份）。

12.7 临时项目（不入库）

• code/bark-notify/：临时测试的 Bark 推送工具，与云超服无关，不纳入项目范围。

---

十三、server-core 分层架构与算力通信规范

13.1 FastAPI 四层架构（单向依赖）

层	职责	server-core 目录（规划）
接口层	接收请求、返回响应、参数校验、路由	app/routers/ + app/schemas/（Pydantic）
业务层	业务逻辑编排、用例（用领域对象实现用例）	app/services/
领域层	核心业务模型与规则（实体 / 值对象 / 领域服务）	app/domain/
基础设施层（含数据模型层）	数据库访问、缓存、消息队列、外部服务适配	app/infrastructure/（repositories/、models/、cache/、mq/）

依赖方向（单向，禁止反向依赖）：

接口层 → 业务层 → 领域层
  ↘        ↘        ↘
    基础设施层（数据模型 / DB / 缓存 / MQ / 外部服务）

• 接口层只做「收请求 → 调业务层 → 返回响应」；业务层不依赖接口层。
• 领域层是核心模型与规则，不依赖业务层 / 接口层 / 基础设施层的具体实现（只面向其接口）。
• 基础设施层实现接口，不得反向依赖上层。

全异步：接口层 async def → 业务层 async → 仓储 async（SQLAlchemy async），事件循环内杜绝阻塞调用；外部 HTTP 用 httpx.AsyncClient。见 13.4。

13.2 算力通信规范

• 内部：FastAPI（server-core）与算力调度服务（compute-engine / 算力引擎）经内部 IP / loopback 交互（http://127.0.0.1:3000），不经过公网。
• 对外：前端 / 用户的算力调用统一走服务端 /api/v1（server-core 统一入口），不直连算力引擎。
• 算力引擎（new-api）仅作服务被消费，无页面暴露；额度 / 令牌 / 流水由服务端算力服务程序化管理（见 §4.3）。

13.3 参考工程化：PineSoundServer

server-core 的工程化（数据目录 / 容器启动 / 运维脚本）参考 C:\Users\Administrator\MyCode\PineSoundServer：

• serverdata/：数据目录规范（logs/ data/ files/ keys/ prompts/ + 各中间件数据 emqx-data/ redis-data/ minio/ milvus/）。
• serverrun/：容器与微服务启动（start-all.sh 编排、各服务 docker-compose.yml、envcopy.sh 配置加密、encrypt-certs.sh 证书加密）。
• ops/：运维脚本（init_admin / db_backup / 数据迁移 / clear_redis_tokens / 算力套餐与分区初始化等）。

13.4 异步与并发（设计之初即考虑）

全异步调用链：接口层 async def → 业务层 async → 仓储 async（SQLAlchemy async）。事件循环内杜绝阻塞（不用 time.sleep / 同步 IO；外部调用统一 httpx.AsyncClient 带超时 / 重试 / 熔断）。

服务	异步方案	要点
MySQL	SQLAlchemy 2.0 create_async_engine + async session（asyncmy / aiomysql）	连接池（pool_size / max_overflow / pool_pre_ping）；每请求独立 async session（async with 管事务边界）；开发环境 aiosqlite
Redis	redis.asyncio	会话 / 缓存 / 限流 / 分布式锁（SET NX EX）；连接池
OSS 对象存储	异步封装（阿里云 OSS / MinIO，aioboto3 或 oss2 线程池包装）	上传异步、断点续传、回调通知，不阻塞请求线程

并发正确性：

• 写操作（抢单 / 扣款 / 报名 / 领券）用行锁（SELECT ... FOR UPDATE）+ 幂等键，防并发重复。
• 乐观锁（version 字段）处理并发更新冲突。
• 事务边界清晰：多表写（如 _adopt_phone、结算 + 佣金）包在一个事务内。
• 外部依赖（算力引擎 / 云厂商）异步调用 + 超时重试，失败可降级。

---

附：与既有设计文档的关系

• 本设计是「三端架构设计.md（培训三端）」与「身份体系与端口权限设计方案.md（云超服七端口）」的合一演进：培训业务并入云超服端口体系。
• 云超服平台全量方案设计.md 的六端口管理功能，本设计以「已实现（RBAC/任务/内容/补贴）+ 本次新增（课程/活动/报名/测评/算力/入驻/财务/工商/园区）」两栏承接。
• 大屏升级以 code/park-desktop/backend/README.md 为权威基线，本设计只描述数据源与对接改造。