后端结构
.
cmd/server
configs/config.yaml
internal/api
internal/application
internal/bootstrap
internal/domain
internal/infrastructure
internal/policy
internal/platform
internal/repository
migrations模块职责
api: HTTP 传输层、middleware、请求解析和响应封装。application: 用例编排、授权、作用域语义、审计、操作日志和面向前端的 view model。bootstrap: 依赖图装配、数据库迁移、内置种子和启动生命周期。domain: 领域契约和平台 view model。infrastructure: config、logger、PostgreSQL、Kubernetes、informer、Agent client、Swagger、MCP 和外部系统 client。policy: RBAC、ABAC 和 scope 计算。repository: 审计、业务记录、运行时记录等持久化访问。
模块化单体约定
后端保持单仓库、单 go.mod 的模块化单体形态。cmd/server 是当前管理控制面入口;远程集群 agent 和 runner 位于主仓 github.com/opensoha/soha 的 agent/ 独立 Go 子模块。未来如果增加内网安全工作台或设备上报能力,优先通过明确 API/契约边界新增独立入口或仓库,而不是把高频设备上报直接塞进 cmd/server 的 Gin handler。
新增入口必须复用 internal/bootstrap、internal/infrastructure、internal/repository 和 internal/application 中的稳定能力。只有入口生命周期、监听地址、认证方式、队列/worker 循环等运行形态差异应该留在 cmd/** 或专门的 bootstrap 文件中。
路由注册约定
internal/api/routes/router.go 只负责 Gin engine、全局 middleware、基础兼容路径、静态资源和顶层 route group 装配。业务路由要落在同包的领域文件中,例如:
routes_public.go: health、登录、公开 webhook、runner claim/callback 等无需用户会话但需要 token 或公开协议的入口。routes_protected.go: 受登录态保护的顶层编排函数。routes_platform.go: Kubernetes 平台管理资源。routes_delivery.go: 应用交付、执行任务、发布和制品。routes_monitoring.go: 监控、告警、通知和值班。routes_runtime.go: 虚拟化、Docker、AI workbench 等运行时工作台。routes_governance.go: system、access、settings、AI Gateway、audit/operation 等治理面。
新增领域不要继续膨胀 router.go。先新增 registerDomainRoutes 这种领域注册函数,再从 registerProtectedRoutes 或 registerPublicRoutes 中接入。模块开关、公开 callback 路径、用户登录态路径要保持边界清晰。
Go 热点文件拆分约定
大文件优化优先做同包机械拆分,再做行为调整。拆分时应保持 receiver、私有 helper、DTO、错误语义和 audit/operation 记录不变。
- 平台 handler REST 方法按资源域拆分:
platform_inventory.go、platform_workloads.go、platform_configuration.go、platform_network.go、platform_storage.go、platform_rbac.go、platform_crd_helm.go、platform_generic.go和platform_observability.go。WebSocket 流处理归platform_streams.go,共享的websocketStreamSessionlifecycle helper 也保留在这里。 - 平台资源 application service 按资源族拆分:
pods.go/pods_helpers.go、workloads.go、configuration.go、rbac.go、network.go、storage.go、crd.go、events.go和resource_yaml.go。共享授权/审计 helper 归common.go,direct Kubernetes bundle/timeout helper 归direct_query.go。 - 修改资源服务行为时保持现有资源族边界,并至少运行
go test ./internal/application/resource。机械移动和 agent/direct 行为调整不要混在同一 patch 中。 - 执行面状态机必须有测试保护。claim/callback/cancel/retry/timeout、callback token 轮换、terminal 状态 late callback、artifact 落库和 build/release 回填都属于执行面测试范围。
- AI Gateway 按行为域拆分:
manifest.go、tools.go、policies.go、rate_limit_budget.go、redaction.go、approval.go、tokens.go、audit.go和governance.go。service.go只保留 wiring、interface、constructor 和 setter。 - transport 行为发生变化时需要 handler 测试;纯文件移动可先依赖 package compile、全量 Go test 和路由注册对比。
Bootstrap 和 Seed 约定
internal/bootstrap/app.go 保持顶层依赖装配。生命周期方法属于 lifecycle.go,跨模块窄适配器属于独立文件,例如 Docker 主机快速创建只通过 docker_provisioner.go 调用虚拟化服务。
数据库 bootstrap 也按关注点拆分。database.go 保留 seed 编排、角色/策略/用户/集群等通用持久化 helper;菜单 seed、模块禁用过滤、菜单角色绑定和内置菜单升级逻辑归 database_menus.go。未来增加领域菜单或权限时,应优先在对应 seed 文件中落位,并同步权限键、菜单可见性、前端 route metadata 和文档。
网络访问工作台边界
网络访问工作台已经拆为三个控制入口和独立数据面:
/api/v1/network-access/**:cmd/server中的管理、策略和审计 API。/api/network-control/v1/**:cmd/network-control承载的端点、NAS 和网关控制 API。/api/ingest/v1/**:cmd/ingest承载的心跳、Accounting 和聚合遥测 API,使用独立数据库。cmd/network-gateway:独立 WireGuard/nftables 数据面,不承载管理 API。
Soha 负责设备、站点、策略、租约、授权、降级和审计。FreeRADIUS 负责 EAP/RADIUS,mihomo 负责端点代理执行;它们都不成为 Soha 主进程的运行时核心或权限真实源。具体部署和验收见网络访问工作台运维指南。