Skip to Content
开发后端结构

后端结构

. 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,共享的 websocketStreamSession lifecycle 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 主进程的运行时核心或权限真实源。具体部署和验收见网络访问工作台运维指南。

Last updated on