kami_gateway/.qoder/repowiki/zh/content/部署与配置/环境变量管理.md

环境变量管理

**本文档引用的文件** - [Dockerfile](file://deploy/Dockerfile#L1-L44) - [docker-compose.yaml](file://deploy/docker-compose.yaml#L1-L24) - [docker-compose-local.yaml](file://deploy/docker-compose-local.yaml#L1-L18) - [build.sh](file://build.sh#L1-L2) - [app.conf](file://conf/app.conf#L1-L78) - [config.go](file://internal/config/config.go#L1-L45)

目录

1. 简介
2. 预设环境变量
3. 环境变量覆盖机制
4. 构建脚本与版本控制
5. 实际应用案例
6. 环境变量与配置文件优先级
7. 总结

简介

kami_gateway 项目通过环境变量实现灵活的运行时配置，支持开发、测试和生产等多环境部署。本项目利用 Docker 和 docker-compose 提供了完整的容器化部署方案，并通过环境变量机制实现配置的动态注入与覆盖。环境变量不仅用于服务地址配置，还涉及代理服务、认证信息等关键参数，是系统可配置性的核心组成部分。

Section sources

• Dockerfile
• docker-compose.yaml

预设环境变量

在 Dockerfile 中通过 ENV 指令预设了一系列环境变量，这些变量为系统提供了默认配置：

• serverName: 服务器名称，默认值为"默认"
• gatewayAddr: 网关地址，初始为空
• portalAddr: 门户地址，初始为空
• shopAddr: 商城地址，初始为空
• proxy: 代理地址，初始为空
• proxyName: 代理名称，默认为"qkgo"
• proxyUrl: 代理获取URL，默认指向 qg.net 的代理服务
• proxyAuthKey: 代理认证密钥，默认为"7ASQH2BI"
• proxyAuthPwd: 代理认证密码，默认为"34D6652FE7B6"

这些环境变量在容器构建时被设置，为应用提供了基础的运行配置。

Section sources

• Dockerfile

环境变量覆盖机制

kami_gateway 支持通过多种方式覆盖 Dockerfile 中预设的环境变量，实现不同环境的灵活配置。

在 docker-compose.yaml 文件中，虽然没有显式定义 environment 字段来覆盖环境变量，但通过外部卷挂载机制实现了配置的外部化：

volumes:
  - /data/kami/gateway/conf/:/app/conf/
  - /data/kami/gateway/logs/:/app/logs/

这种设计允许通过挂载外部配置文件来间接影响环境变量的行为。

而在 docker-compose-local.yaml 中，通过简化配置实现了本地开发环境的快速部署，保留了构建上下文但简化了网络和端口配置。

运行时可以通过 docker run 命令的 -e 参数或在 docker-compose.yml 的 environment 字段中直接覆盖这些变量，例如：

docker run -e serverName="开发环境" -e gatewayAddr="http://dev.gateway:12309" kami_gateway

Section sources

• docker-compose.yaml
• docker-compose-local.yaml

构建脚本与版本控制

build.sh 脚本定义了项目的构建过程，其中包含了与环境变量相关的构建参数：

CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build main.go

虽然该脚本本身不直接处理环境变量，但在 docker-compose.yaml 中使用了 $VERSION 环境变量来控制镜像标签：

image: kami_gateway:$VERSION

这种设计允许在构建时通过传递不同的 VERSION 值来生成不同标签的镜像，实现版本控制。例如，可以通过以下命令构建特定版本的镜像：

VERSION=v1.2.0 docker-compose build

这使得 CI/CD 流程能够根据 Git 标签或构建号自动创建相应版本的镜像，提高了部署的可追溯性和一致性。

Section sources

• build.sh
• docker-compose.yaml

实际应用案例

环境变量在 kami_gateway 中有多种实际应用场景。

动态数据库配置

虽然数据库连接信息主要在 app.conf 中定义，但可以通过环境变量实现动态配置。例如，可以修改配置读取逻辑，从环境变量中获取数据库连接参数：

dbhost := os.Getenv("MYSQL_HOST")
dbport := os.Getenv("MYSQL_PORT")

这样可以在不同环境中使用不同的数据库实例，而无需修改配置文件。

代理服务切换

通过 proxyUrl、proxyAuthKey 和 proxyAuthPwd 环境变量，可以轻松切换不同的代理服务提供商。在开发环境中可以使用测试代理，在生产环境中切换到付费的高稳定性代理服务。

多环境部署

通过组合使用不同的环境变量，可以实现一套代码在多个环境中的部署：

• 开发环境：serverName="开发"，gatewayAddr="http://localhost:12309"
• 测试环境：serverName="测试"，gatewayAddr="http://test.gateway:12309"
• 生产环境：serverName="生产"，gatewayAddr="https://api.gateway.com"

这种机制确保了配置的灵活性和安全性，敏感信息可以通过环境变量而非配置文件进行管理。

Section sources

• app.conf
• Dockerfile

环境变量与配置文件优先级

在 kami_gateway 中，环境变量与 app.conf 配置文件之间存在明确的优先级关系。

根据 internal/config/config.go 中的配置读取逻辑，系统使用 beego 框架的 web.AppConfig.String() 方法读取配置值。beego 框架默认支持环境变量覆盖配置文件中的值，即当同名环境变量存在时，会优先使用环境变量的值。

例如，app.conf 中定义了 httpport = 12309，但可以通过设置 httpport 环境变量来覆盖此值。这种设计模式使得关键配置既可以在配置文件中提供默认值，又可以通过环境变量在部署时进行灵活调整。

对于 shop::key 这样的配置项，GetMerchantKey() 函数直接从配置中读取，这意味着可以通过环境变量 shop__key（beego 将双下划线转换为配置节分隔符）来覆盖商户密钥，增强了配置的安全性。

Section sources

• app.conf
• config.go

总结

kami_gateway 项目通过精心设计的环境变量机制，实现了高度灵活的配置管理。从 Dockerfile 中的预设变量，到 docker-compose 的部署配置，再到运行时的动态覆盖，形成了完整的配置管理体系。这种设计不仅支持多环境部署，还提高了系统的可维护性和安全性。通过将敏感信息和环境特定配置从代码中分离，项目能够更好地适应不同的部署场景，同时保持代码库的整洁和一致性。