联犀开发者文档

配置文件与环境变量

约 974 字大约 3 分钟

2025-03-03

平台配置由结构体、YAML 和环境变量共同组成。本文说明 share/utils 的配置加载器行为；单个服务新增字段时，仍需在它自己的 internal/config 声明。

配置从哪里加载

服务调用 utils.ConfLoad 或 utils.ConfMustLoad 加载指定文件。前者返回错误，后者在错误时终止启动。相对路径先按工作目录解析，再尝试可执行文件所在目录。

加载器在选中的配置目录中寻找 common.yaml，将公共配置和服务配置合并后解析；不要把另一个目录的 common.yaml 当成自动全局配置。运行方式变更时先确认工作目录和配置文件参数。

etc/
├── common.yaml       # 当前目录下服务共用配置
├── demo.yaml         # demo 服务配置
└── ...

配置结构与 YAML

下面为配置结构片段，放在本服务 internal/config/config.go，包名和已有字段沿用当前服务：

// 本文件定义演示服务的关系数据库与 RPC 配置。
package config

import "gitee.com/unitedrhino/share/conf"

// Config 保存服务启动所需配置，字段名与 YAML 配置对应。
type Config struct {
    Database conf.Database      // 关系数据库连接及迁移开关。
    SysRpc   conf.RpcClientConf  // 系统服务调用方式和连接参数。
}
Database:
  DBType: ${dbType:-pgsql}
  DSN: ${dbDSN}
  IsInitTable: ${dbIsInitTable:-true}
SysRpc:
  Mode: grpc
  Conf:
    Endpoints:
      - ${SYS_RPC_ENDPOINT}

先在本机设置 dbDSN 和 SYS_RPC_ENDPOINT。DSN 使用所选数据库驱动的原生格式；不把实际口令写进示例、代码或 Git。

环境变量规则

加载器支持 $VAR、${VAR} 和 ${VAR:-default}。结构体上的 env=... 标签也会参与解析，变量拼写与大小写要完全一致。

变量对应能力注意
dbType关系库类型mysql、pgsql 或 sqlite
dbDSN关系库连接串必需信息，日志中脱敏
dbIsInitTable启动表结构初始化由服务迁移代码使用，不能代替迁移实现
dbTLSCAFileMySQL 自定义 CA使用时路径必须在运行容器中可读
tsDBType、tsDBDriver、tsDBDSN时序库类型与驱动须匹配
OssCustomHost文件访问域名覆盖URL 可达性与文件权限分开检查

引用 share/conf 的服务包含 .env 自动加载。.env 与启动工作目录有关，不保证从任意位置运行都能找到可执行文件旁的 .env。Compose 的 env_file、宿主机环境变量和应用自行读 .env 也是不同环节。

按前后缀选择配置

confPrefix、confSuffix 用于尝试配置文件的变体；只有对应文件存在时才采用，否则回退原文件，公共配置也按相同规则查找。两者在包初始化阶段读取，必须在进程启动前设置。

为避免配置指向不确定，新环境先在本地核对实际选中文件，再启动正式服务；不要假定设置了变量就一定加载到了专用配置。

可选模块和故障排查

WithMissingAsEmpty 适合带显式 Enable 开关的可选模块，不能用来掩盖数据库、认证等必需配置缺失。

现象检查顺序
本机启动正常，容器缺字段容器工作目录、挂载路径、环境变量是否传入
修改 .env 后行为未变重启进程、检查进程实际工作目录与同名环境变量
切换环境后仍使用旧库配置文件是否存在、前后缀回退、DSN 来源
可选服务导致启动失败是否带启用开关，禁用时是否仍初始化客户端

验证配置时只记录字段是否就绪及所选配置，不输出完整 DSN、令牌和私钥。数据库迁移见数据库开发，外部 RPC 连接见连接平台服务。

更新日志

2026/10/16 19:46
查看所有更新日志
  • b3b4d-docs(平台开发): 恢复有效专题并更新当前实现示例于