架构总览

GopherForge 后端按域拆分为 16 个 API 服务，AI worker 内嵌在 ai-service 进程中，另有 shared 公共库；前端单页应用、Traefik 网关统一入口与鉴权。Hermes 客户端和 FreeSWITCH 媒体栈独立启动，外部供应商需用户配置。

交互式基础平台子图

下图保留基础平台的 7 服务示意，不包含新增业务域；完整服务范围以本页表格为准。

在新页面全屏打开

服务清单

服务	职责
auth	登录注册、JWT Access/Refresh 签发与吊销、验证码、TOTP 两步验证、OAuth 三方登录、网关 ForwardAuth 统一验签
identity	用户、角色、权限、部门、岗位、租户与套餐 CRUD，数据范围（数据权限），租户隔离 GORM 插件
system	菜单、字典、公告、系统设置（DB 热配置）、在线用户、短信、错误码、代码生成器
audit	登录日志、操作日志、审计日志查询；经 NATS 持久消费登录事件
file	文件上传下载（本地 / MinIO / S3 兼容云）
monitor	服务器/PostgreSQL/Redis 监控、定时任务、健康检查、Prometheus metrics；持有共享 goose 迁移与网关兜底路由
bpm	轻量审批流引擎（详见审批流）
ai	AI 对话、知识库、Agent、工位与独立 worker
crm	客户、线索、分配与跟进
im	即时消息、会话、访客与词库
pay	支付配置、订单与回调
mp	公众号内容与消息
notify	通知渠道、模板与投递
ticket	工单、事件与参与者
cc	坐席、话单、计费、报表与语音配置
visibility	业务可视化与看板
shared	同一 Go module 内的共享包，不是独立服务

请求链路

浏览器
  └─▶ Traefik 网关 :8000
        ├─ ForwardAuth ─▶ auth（验签，注入 X-Auth-* 头）
        └─ 按 PathPrefix 路由 ─▶ 各服务
                                   └─ 只信任网关注入的 X-Auth-User-ID /
                                      X-Auth-Tenant-ID 等头

三条安全约定：

服务不裸奔：宿主机端口默认只绑 loopback，外部流量一律经网关。
鉴权集中：受保护路由挂 ForwardAuth 中间件，业务服务不自行解析 JWT（内网直连场景才走 Bearer 兜底）。
服务间内部调用用 X-Internal-Token 共享密钥，不复用用户态凭证。

数据层

PostgreSQL 18（pgvector 镜像）单实例共享库，各服务表按前缀隔离。
迁移单一真源：goose 版本化 SQL 统一放在 services/monitor/migrations/，由 migrate 容器在启动时执行；实验线服务（如 bpm）的自管表走 GORM AutoMigrate（详见 MIGRATIONS 约定）。
Redis 8：限流、在线用户、令牌黑名单、权限缓存。
NATS JetStream：登录事件从 auth 解耦到 audit（持久消费，服务重启不丢）。

前端

React 19 + TypeScript + Vite 8 + Ant Design 6，Redux Toolkit 状态管理，Axios 拦截器统一解包 {code, message, data} 响应与无感刷新 Token。深空暗色 / 白蓝亮色双主题。

菜单与路由：菜单由后端种子数据下发（RBAC 过滤），前端静态路由表映射组件；新增页面需要同时补路由与菜单种子（见二次开发）。

前端的技术栈、目录结构、请求层、路由权限、页面规范、状态与主题、演示模式的专门文档见导航「前端开发」分组。写新页面之前请先读页面开发规范——统一列表页三件套与组件约定，能省很多返工。

可观测（可选开启）

Prometheus 指标 + Grafana 看板配置在 platform/deploy/；OpenTelemetry + Jaeger 链路追踪按 env 开关接入。每个服务暴露 /api/v1/health/live 与 /ready。

工程门禁

CI（GitHub Actions）对每个服务独立跑 go test + go vet，前端 lint + build + 依赖审计，外加三道特色门禁：

OpenAPI 契约漂移检测：路由改了但 openapi.json 没更新会红。
迁移彩排：migration-rehearsal 在干净库上预演全部迁移。
集成冒烟：全栈 compose 拉起后 API 冒烟 + Playwright E2E。

架构总览 ​

交互式基础平台子图 ​

服务清单 ​

请求链路 ​

数据层 ​

前端 ​

可观测（可选开启） ​

工程门禁 ​