跳到主要内容

Server 配置

本文说明 testudo-server 的运行配置文件位置、Helm 部署时的配置来源、各字段作用，以及 Swagger / OpenAPI 文档开关应该在哪里配置。

配置文件在哪里​

当前 disaster-server 固定读取相对路径：

configs/config.yaml

代码中的默认路径常量是：

configs.DefaultConfigPath = "configs/config.yaml"

配置会在 server 启动前加载并校验；server.host、server.port、server.namespace 为空时，server 不能正常启动。

注意

当前代码没有把命令行 --config 参数接到配置加载逻辑上。排查配置不生效时，应先确认进程工作目录下是否存在 configs/config.yaml，不要假设传入其他路径就会生效。

不同启动方式下的配置来源​

场景配置来源说明
在源码仓库本地启动disaster-server/configs/config.yaml从仓库根目录启动时，相对路径会命中该文件。
使用 server 容器镜像/app/configs/config.yaml镜像 WORKDIR 是 /app，并内置一份默认配置。
使用 Helm 部署Helm values 中的 configs.configYamlChart 渲染成 ConfigMap，挂载到 /app/configs/config.yaml。

Helm 部署时，实际修改入口是 values：

configs:
  configYaml: |
    server:
      host: "0.0.0.0"
      port: 8080
      namespace: disaster-system

Chart 会把这段内容渲染为 config.yaml，再通过 volume mount 覆盖容器内文件：

/app/configs/config.yaml

修改 ConfigMap 或 Helm values 后，需要让 server Pod 重新加载配置。对 Helm 发布来说，按升级流程重新部署并确认 Pod 已滚动更新。

一份最小配置​

server:
  host: "0.0.0.0"
  port: 8080
  env: "prod"
  namespace: disaster-system

log:
  level: info

jwt:
  secret: "replace-with-a-long-random-secret"
  access_expire: 24h
  refresh_expire: 168h

swagger:
  enabled: false

license:
  enabled: true
  namespace: ""
  caPath: /var/run/secrets/kubernetes.io/serviceaccount/ca.crt

字段说明​

server​

字段是否关键说明
server.host是Hertz 监听地址。容器内通常使用 0.0.0.0。
server.port是Hertz 监听端口。默认示例为 8080。Service 端口和容器端口需要与部署配置对应。
server.env是鉴权边界开关。当前代码中，当值为 dev 时 /apis 和受保护的 /api 路由不会挂 JWT 中间件；非 dev 环境会启用 JWT 中间件。
server.namespace是管理集群中 server 读取和写入 Testudo 资源的命名空间。默认值为 disaster-system。

生产环境不要把 server.env 配成 dev。否则除登录和公开接口以外，本应受 JWT 保护的 server API 也会绕过业务鉴权中间件。

log​

字段说明
log.level当前支持 debug、info、error。未知值按 info 处理。

LogConfig 结构中还保留了 output 字段，但当前启动逻辑只读取 log.level。

jwt​

字段说明
jwt.secretJWT 签名密钥。非本地开发必须替换默认示例值，并避免写入公开仓库。
jwt.access_expireAccess Token 有效期。未配置时当前代码回退为 24h。
jwt.refresh_expireRefresh Token 有效期。未配置时当前代码回退为 168h。

示例配置中仍可能看到 jwt.timeout 或结构体中的 jwt.realm。当前鉴权实现实际使用 access_expire、refresh_expire 和 secret；不要用 timeout 代替 Access Token 过期时间。

swagger​

字段说明
swagger.enabled是否注册 Swagger / OpenAPI 文档路由。代码默认值是 false。

开启后，server 暴露：

路径说明
/swagger/Swagger UI。
/openapi.yamlOpenAPI YAML。
/openapi.json从 YAML 转换得到的 OpenAPI JSON。

示例：

swagger:
  enabled: true

Swagger / OpenAPI 契约源文件在 server 仓库中：

openspec/specs/disaster-server-openapi.yaml

swagger.enabled 只控制运行中 server 是否注册文档路由，不改变契约文件内容。Swagger 路由不挂业务 JWT 中间件，生产环境如需开启，应通过内网、网关、Ingress 白名单或其他外层访问控制收敛暴露面。更多维护规则见 Swagger / OpenAPI 文档。

license​

字段说明
license.enabled是否启用与 License 相关的 server 逻辑。当前默认值为 true。
license.namespaceLicense 相关资源所在命名空间。留空时使用 server.namespace。
license.caPathserver 访问集群 API 时读取的 CA 文件路径。Pod 内默认使用 ServiceAccount CA。

Kubernetes 连接配置不在这里​

configs/config.yaml 不保存管理集群 kubeconfig，也不保存业务集群 kubeconfig。

  • server 访问管理集群时，优先使用 Pod 内的 in-cluster config。
  • 本地运行时，如果不在集群内，会回退到当前用户的 $HOME/.kube/config。
  • 源集群和目标集群的连接信息由平台集群配置保存，server 根据 Cluster 资源中的 kubeconfig 或 token/endpoint 建立远端客户端。

因此，业务集群不可达时，不要先改 server YAML；应检查平台注册的集群配置、网络和凭据。

常见修改​

关闭生产 Swagger​

swagger:
  enabled: false

修改管理命名空间​

server:
  namespace: disaster-system

license:
  namespace: ""

license.namespace 留空时会跟随 server.namespace。如果 License 资源需要放到不同命名空间，再显式填写。

修改 Token 过期时间​

jwt:
  secret: "replace-with-a-long-random-secret"
  access_expire: 12h
  refresh_expire: 168h

排查清单​

现象先检查
server 启动时报配置读取失败进程工作目录下是否存在 configs/config.yaml。
Helm 修改后配置不生效values 是否写入 configs.configYaml，ConfigMap 是否更新，Pod 是否重建。
API 在生产环境没有鉴权server.env 是否误设为 dev。
/swagger/ 返回 404swagger.enabled 是否为 true，server 是否已重启。
/openapi.yaml 返回找不到 specserver 运行镜像或工作目录中是否包含 openspec/specs/disaster-server-openapi.yaml。
远端业务集群连接失败平台集群凭据、远端 API 地址、网络和证书，而不是 server YAML。