跳到主要内容

配置与环境变量说明

概述​

本文档详细说明了井云服务中心后端系统的所有配置项、环境变量、默认值和安全级别，为开发、测试和生产环境的部署提供完整的配置指南。

配置架构​

配置层级​

配置优先级（从低到高）：

  1. 默认配置：代码内置的默认值
  2. 环境配置：基于环境的配置
  3. 本地配置文件：本地配置文件
  4. 命令行参数：启动时的命令行参数
  5. Consul 动态配置：Consul KV 存储的配置
  6. 环境变量覆盖：环境变量覆盖所有配置

配置来源：

  • 代码内置默认值
  • 配置文件
  • 环境变量
  • 命令行参数
  • Consul KV

配置优先级​

  1. 命令行参数（最高优先级）
  2. 环境变量
  3. Consul 动态配置
  4. 本地配置文件
  5. 环境配置
  6. 默认配置（最低优先级）

通用配置项​

服务基础配置​

服务标识​

server:
  name: "user-service"          # 服务名称
  version: "v1.0.0"            # 服务版本
  environment: "development"    # 环境标识：development/test/staging/production
  region: "cn-north-1"         # 区域标识
  zone: "cn-north-1a"          # 可用区

HTTP 服务配置​

server:
  http:
    addr: "0.0.0.0:8000"       # HTTP 监听地址
    timeout:
      read: "5s"               # 读取超时
      write: "5s"              # 写入超时
      idle: "60s"              # 空闲超时
    middleware:
      logging: true             # 启用日志中间件
      metrics: true            # 启用指标中间件
      tracing: true            # 启用链路追踪
      recovery: true           # 启用恢复中间件
      rate_limit: true         # 启用限流中间件
      cors: true               # 启用 CORS 中间件

gRPC 服务配置​

server:
  grpc:
    addr: "0.0.0.0:9000"       # gRPC 监听地址
    timeout:
      read: "5s"               # 读取超时
      write: "5s"              # 写入超时
    middleware:
      logging: true             # 启用日志中间件
      metrics: true            # 启用指标中间件
      tracing: true            # 启用链路追踪
      recovery: true           # 启用恢复中间件
      auth: true               # 启用认证中间件

数据存储配置​

PostgreSQL 配置​

data:
  database:
    driver: "postgres"
    host: "localhost"          # 数据库主机
    port: 5432                 # 数据库端口
    name: "jingyun"            # 数据库名称
    user: "akita"              # 数据库用户
    password: "chrishy123"     # 数据库密码
    ssl_mode: "disable"        # SSL 模式：disable/require/verify-ca/verify-full
    timezone: "Asia/Shanghai"  # 时区设置
    max_open_conns: 100        # 最大打开连接数
    max_idle_conns: 10         # 最大空闲连接数
    conn_max_lifetime: "1h"    # 连接最大生命周期
    conn_max_idle_time: "10m"  # 连接最大空闲时间

Redis 配置​

data:
  redis:
    addr: "localhost:6379"     # Redis 地址
    password: "chrishy123"     # Redis 密码
    db: 0                      # 数据库编号
    pool_size: 100             # 连接池大小
    min_idle_conns: 10         # 最小空闲连接数
    dial_timeout: "5s"         # 连接超时
    read_timeout: "3s"         # 读取超时
    write_timeout: "3s"        # 写入超时
    pool_timeout: "4s"         # 连接池超时
    idle_timeout: "5m"         # 空闲超时
    idle_check_frequency: "1m" # 空闲检查频率

消息队列配置​

RabbitMQ 配置​

data:
  rabbitmq:
    host: "localhost"          # RabbitMQ 主机
    port: 5672                 # RabbitMQ 端口
    username: "akita"          # 用户名
    password: "chrishy123"     # 密码
    vhost: "/"                 # 虚拟主机
    exchange: "jingyun"        # 默认交换机
    prefetch_count: 10         # 预取数量
    reconnect_interval: "10s"  # 重连间隔
    publish_timeout: "5s"      # 发布超时
    consume_timeout: "30s"     # 消费超时

服务发现配置​

Consul 配置​

consul:
  address: "localhost:8500"    # Consul 地址
  scheme: "http"              # 协议：http/https
  token: ""                   # 访问令牌
  namespace: ""               # 命名空间
  partition: ""               # 分区
  datacenter: "dc1"           # 数据中心
  service:
    name: "user-service"      # 服务名称
    id: "user-service-1"      # 服务 ID
    tags: ["backend", "user"] # 服务标签
    port: 9000                # 服务端口
    address: ""               # 服务地址（空表示自动获取）
    check:
      http: "http://localhost:8000/health"  # 健康检查地址
      interval: "10s"         # 检查间隔
      timeout: "3s"           # 检查超时
      deregister_critical_service_after: "30s" # 失效后注销时间

服务特定配置​

认证服务配置​

JWT 配置​

auth:
  jwt:
    secret: "your-secret-key" # JWT 签名密钥（生产环境必须更改）
    access_token_expire: "2h" # 访问令牌过期时间
    refresh_token_expire: "168h" # 刷新令牌过期时间（7天）
    issuer: "jingyun-backend" # 发行者
    algorithm: "HS256"        # 签名算法

微信登录配置​

auth:
  wechat:
    app_id: "your-app-id"     # 微信应用 ID
    app_secret: "your-app-secret" # 微信应用密钥
    redirect_uri: "https://your-domain.com/auth/wechat/callback" # 回调地址
    scope: "snsapi_userinfo"  # 授权范围
    state_expire: "10m"       # 状态过期时间

短信服务配置​

auth:
  sms:
    provider: "aliyun"        # 提供商：aliyun/tencent/huawei/aws
    aliyun:
      access_key_id: "your-access-key-id"
      access_key_secret: "your-access-key-secret"
      sign_name: "井云科技"
      template_code: "SMS_123456789"
    rate_limit: "5/m"         # 发送频率限制
    code_expire: "5m"         # 验证码过期时间
    code_length: 6            # 验证码长度

用户服务配置​

分销系统配置​

user:
  distribution:
    max_levels: 2             # 最大分销层级
    default_commission_rate: 0.1 # 默认佣金比例（10%）
    min_withdraw_amount: 100   # 最小提现金额（元）
    withdraw_fee_rate: 0.006  # 提现手续费率（0.6%）
    auto_upgrade: true        # 自动升级分销等级
    upgrade_check_time: "03:00" # 升级检查时间

点数系统配置​

user:
  points:
    default_expire_days: 365  # 默认过期天数
    fifo_consume: true        # FIFO 消费策略
    batch_size: 100           # 批处理大小
    expire_check_time: "02:00" # 过期检查时间
    transaction_retention_days: 1095 # 交易记录保留天数

智能体服务配置​

Coze 平台配置​

agent:
  coze:
    api_url: "https://api.coze.cn" # Coze API 地址
    api_key: "your-api-key"   # API 密钥
    timeout: "30s"            # 请求超时
    retry_count: 3            # 重试次数
    sync_interval: "1h"       # 同步间隔
    batch_size: 50            # 批量同步大小

文件上传配置​

agent:
  upload:
    provider: "aliyun"        # 存储提供商：local/aliyun/tencent/aws
    max_file_size: "100MB"    # 最大文件大小
    allowed_types: [".jpg", ".jpeg", ".png", ".gif", ".webp", ".mp4", ".mov"] # 允许的文件类型
    aliyun:
      endpoint: "https://oss-cn-beijing.aliyuncs.com"
      access_key_id: "your-access-key-id"
      access_key_secret: "your-access-key-secret"
      bucket: "jingyun-assets"
      base_url: "https://jingyun-assets.oss-cn-beijing.aliyuncs.com"

租户服务配置​

租户管理配置​

tenant:
  domain:
    base_domain: "jingyun.design" # 基础域名
    prefix_length: 6        # 域名前缀长度
    reserved_names: ["www", "api", "admin", "test", "dev"] # 保留域名
    max_length: 20          # 最大长度
  menu:
    max_depth: 5            # 菜单最大深度
    max_children: 100       # 最大子菜单数量
  snapshot:
    retention_days: 2555    # 快照保留天数（7年）

支付服务配置​

微信支付配置​

payment:
  wechat:
    app_id: "your-app-id"   # 微信应用 ID
    mch_id: "your-mch-id"   # 商户号
    api_key: "your-api-key" # API 密钥
    api_cert_path: "/path/to/cert.pem" # 证书路径
    api_key_path: "/path/to/key.pem"   # 私钥路径
    notify_url: "https://your-domain.com/payment/wechat/notify" # 回调地址
    expire_time: "2h"       # 订单过期时间
  order:
    timeout: "30m"          # 支付超时时间
    retry_count: 3          # 重试次数
    callback_timeout: "30s" # 回调超时

集成服务配置​

微信第三方平台配置​

integration:
  wechat_third_party:
    component_app_id: "your-component-app-id" # 第三方平台 AppID
    component_secret: "your-component-secret" # 第三方平台 Secret
    component_token: "your-component-token"   # 验证票据
    component_encoding_aes_key: "your-encoding-aes-key" # 消息加密密钥
    callback_url: "https://your-domain.com/integration/wechat/third-party/callback" # 回调地址
    auth_redirect_url: "https://your-domain.com/auth/wechat/third-party" # 授权重定向地址
    refresh_token_expire: "720h" # 刷新令牌过期时间（30天）

环境变量配置​

通用环境变量​

服务基础配置​

# 服务标识
SERVER_NAME=user-service
SERVER_VERSION=v1.0.0
SERVER_ENVIRONMENT=production
SERVER_REGION=cn-north-1
SERVER_ZONE=cn-north-1a

# HTTP 服务
SERVER_HTTP_ADDR=0.0.0.0:8000
SERVER_HTTP_TIMEOUT_READ=5s
SERVER_HTTP_TIMEOUT_WRITE=5s
SERVER_HTTP_TIMEOUT_IDLE=60s

# gRPC 服务
SERVER_GRPC_ADDR=0.0.0.0:9000
SERVER_GRPC_TIMEOUT_READ=5s
SERVER_GRPC_TIMEOUT_WRITE=5s

数据库配置​

# PostgreSQL
DATA_DATABASE_DRIVER=postgres
DATA_DATABASE_HOST=localhost
DATA_DATABASE_PORT=5432
DATA_DATABASE_NAME=jingyun
DATA_DATABASE_USER=akita
DATA_DATABASE_PASSWORD=chrishy123
DATA_DATABASE_SSL_MODE=disable
DATA_DATABASE_TIMEZONE=Asia/Shanghai
DATA_DATABASE_MAX_OPEN_CONNS=100
DATA_DATABASE_MAX_IDLE_CONNS=10

# Redis
DATA_REDIS_ADDR=localhost:6379
DATA_REDIS_PASSWORD=chrishy123
DATA_REDIS_DB=0
DATA_REDIS_POOL_SIZE=100
DATA_REDIS_MIN_IDLE_CONNS=10

消息队列配置​

# RabbitMQ
DATA_RABBITMQ_HOST=localhost
DATA_RABBITMQ_PORT=5672
DATA_RABBITMQ_USERNAME=akita
DATA_RABBITMQ_PASSWORD=chrishy123
DATA_RABBITMQ_VHOST=/
DATA_RABBITMQ_EXCHANGE=jingyun
DATA_RABBITMQ_PREFETCH_COUNT=10

服务发现配置​

# Consul
CONSUL_ADDRESS=localhost:8500
CONSUL_SCHEME=http
CONSUL_TOKEN=
CONSUL_NAMESPACE=
CONSUL_PARTITION=
CONSUL_DATACENTER=dc1

服务特定环境变量​

认证服务​

# JWT 配置
AUTH_JWT_SECRET=your-secret-key
AUTH_JWT_ACCESS_TOKEN_EXPIRE=2h
AUTH_JWT_REFRESH_TOKEN_EXPIRE=168h
AUTH_JWT_ISSUER=jingyun-backend
AUTH_JWT_ALGORITHM=HS256

# 微信登录
AUTH_WECHAT_APP_ID=your-app-id
AUTH_WECHAT_APP_SECRET=your-app-secret
AUTH_WECHAT_REDIRECT_URI=https://your-domain.com/auth/wechat/callback

# 短信服务
AUTH_SMS_PROVIDER=aliyun
AUTH_SMS_ALIYUN_ACCESS_KEY_ID=your-access-key-id
AUTH_SMS_ALIYUN_ACCESS_KEY_SECRET=your-access-key-secret
AUTH_SMS_ALIYUN_SIGN_NAME=井云科技
AUTH_SMS_ALIYUN_TEMPLATE_CODE=SMS_123456789

支付服务​

# 微信支付
PAYMENT_WECHAT_APP_ID=your-app-id
PAYMENT_WECHAT_MCH_ID=your-mch-id
PAYMENT_WECHAT_API_KEY=your-api-key
PAYMENT_WECHAT_API_CERT_PATH=/path/to/cert.pem
PAYMENT_WECHAT_API_KEY_PATH=/path/to/key.pem
PAYMENT_WECHAT_NOTIFY_URL=https://your-domain.com/payment/wechat/notify

集成服务​

# 微信第三方平台
INTEGRATION_WECHAT_THIRD_PARTY_COMPONENT_APP_ID=your-component-app-id
INTEGRATION_WECHAT_THIRD_PARTY_COMPONENT_SECRET=your-component-secret
INTEGRATION_WECHAT_THIRD_PARTY_COMPONENT_TOKEN=your-component-token
INTEGRATION_WECHAT_THIRD_PARTY_COMPONENT_ENCODING_AES_KEY=your-encoding-aes-key

配置安全级别​

安全级别分类​

1. 公开配置（Public）​

  • 服务名称和版本
  • 监听地址和端口
  • 超时时间配置
  • 日志级别配置
  • 中间件开关

特点：

  • 可以在代码中硬编码
  • 可以在日志中显示
  • 可以在前端暴露

2. 内部配置（Internal）​

  • 数据库连接参数
  • 缓存配置参数
  • 消息队列配置
  • 服务发现配置
  • 业务逻辑配置

特点：

  • 不能在代码中硬编码
  • 不能在日志中显示
  • 只能在内网环境使用

3. 敏感配置（Sensitive）​

  • 数据库密码
  • API 密钥
  • 第三方服务凭证
  • JWT 签名密钥
  • 加密密钥

特点：

  • 必须通过环境变量或密钥管理系统提供
  • 绝对不能在日志中显示
  • 必须加密存储和传输
  • 需要定期轮换

4. 机密配置（Secret）​

  • 私钥文件
  • 证书文件
  • 根密码
  • 管理员凭证
  • 系统级密钥

特点：

  • 必须使用专门的密钥管理系统
  • 需要严格访问控制
  • 需要审计日志
  • 需要多重保护

配置加密​

1. 传输加密​

  • 所有配置传输使用 HTTPS/TLS
  • 内部服务间配置传输使用 mTLS
  • 敏感配置使用端到端加密

2. 存储加密​

  • 配置文件敏感字段加密
  • 数据库配置记录加密
  • 环境变量敏感值加密

3. 运行时加密​

  • 内存中敏感配置加密
  • 配置解密密钥分离
  • 配置访问权限控制

配置热更新​

支持热更新的配置​

1. 日志配置​

log:
  level: "info"              # 日志级别：debug/info/warn/error
  format: "json"             # 日志格式：json/text
  output: "stdout"           # 输出目标：stdout/file
  file:
    path: "/var/log/app.log" # 日志文件路径
    max_size: "100MB"        # 最大文件大小
    max_age: 30              # 最大保留天数
    max_backups: 10          # 最大备份文件数
    compress: true           # 是否压缩

2. 限流配置​

rate_limit:
  enabled: true              # 是否启用限流
  requests_per_second: 100   # 每秒请求数
  burst: 200                 # 突发请求数
  window_size: "1m"          # 时间窗口大小

3. 缓存配置​

cache:
  ttl: "1h"                  # 默认过期时间
  max_size: 1000             # 最大缓存条目数
  cleanup_interval: "10m"    # 清理间隔

热更新机制​

1. Consul Watch​

func (c *Config) WatchConsul(key string, callback func(interface{})) {
    params := &api.KVListOptions{
        KeysOnly: false,
    }
    
    for {
        kv, _, err := c.consul.KV().List(key, params)
        if err != nil {
            time.Sleep(5 * time.Second)
            continue
        }
        
        if len(kv) > 0 {
            var newConfig interface{}
            if err := json.Unmarshal(kv[0].Value, &newConfig); err == nil {
                callback(newConfig)
            }
        }
        
        time.Sleep(10 * time.Second)
    }
}

2. 文件监控​

func (c *Config) WatchFile(path string, callback func(interface{})) {
    watcher, err := fsnotify.NewWatcher()
    if err != nil {
        return
    }
    defer watcher.Close()
    
    for {
        select {
        case event, ok := <-watcher.Events:
            if !ok {
                return
            }
            if event.Op&fsnotify.Write == fsnotify.Write {
                if newConfig, err := c.loadFromFile(path); err == nil {
                    callback(newConfig)
                }
            }
        case err, ok := <-watcher.Errors:
            if !ok {
                return
            }
            log.Printf("config watch error: %v", err)
        }
    }
}

配置验证​

配置校验规则​

1. 必填项验证​

type Config struct {
    Database DatabaseConfig `yaml:"database" validate:"required"`
    Redis    RedisConfig    `yaml:"redis" validate:"required"`
    Server   ServerConfig   `yaml:"server" validate:"required"`
}

func (c *Config) Validate() error {
    validate := validator.New()
    return validate.Struct(c)
}

2. 格式验证​

type DatabaseConfig struct {
    Host     string `yaml:"host" validate:"required,hostname"`
    Port     int    `yaml:"port" validate:"required,min=1,max=65535"`
    Name     string `yaml:"name" validate:"required,alphanum"`
    User     string `yaml:"user" validate:"required,alphanum"`
    Password string `yaml:"password" validate:"required,min=8"`
}

3. 依赖验证​

func (c *Config) ValidateDependencies() error {
    // 检查数据库连接
    if err := c.testDatabaseConnection(); err != nil {
        return fmt.Errorf("database connection failed: %w", err)
    }
    
    // 检查 Redis 连接
    if err := c.testRedisConnection(); err != nil {
        return fmt.Errorf("redis connection failed: %w", err)
    }
    
    // 检查 Consul 连接
    if err := c.testConsulConnection(); err != nil {
        return fmt.Errorf("consul connection failed: %w", err)
    }
    
    return nil
}

配置启动检查​

1. 服务启动前检查​

func (s *Server) Start() error {
    // 1. 加载配置
    if err := s.loadConfig(); err != nil {
        return fmt.Errorf("failed to load config: %w", err)
    }
    
    // 2. 验证配置
    if err := s.config.Validate(); err != nil {
        return fmt.Errorf("invalid config: %w", err)
    }
    
    // 3. 检查依赖
    if err := s.config.ValidateDependencies(); err != nil {
        return fmt.Errorf("dependency check failed: %w", err)
    }
    
    // 4. 启动服务
    return s.startServices()
}

2. 健康检查集成​

func (s *Server) HealthCheck() *HealthStatus {
    status := &HealthStatus{
        Status: "healthy",
        Checks: make(map[string]string),
    }
    
    // 检查数据库
    if err := s.db.Ping(); err != nil {
        status.Status = "unhealthy"
        status.Checks["database"] = "failed: " + err.Error()
    } else {
        status.Checks["database"] = "ok"
    }
    
    // 检查 Redis
    if _, err := s.redis.Ping().Result(); err != nil {
        status.Status = "unhealthy"
        status.Checks["redis"] = "failed: " + err.Error()
    } else {
        status.Checks["redis"] = "ok"
    }
    
    return status
}

环境配置模板​

开发环境配置​

# development.yaml
server:
  environment: "development"
  http:
    addr: "0.0.0.0:8000"
  grpc:
    addr: "0.0.0.0:9000"

data:
  database:
    host: "localhost"
    port: 5432
    name: "jingyun_dev"
    user: "akita"
    password: "chrishy123"
    ssl_mode: "disable"
  redis:
    addr: "localhost:6379"
    password: "chrishy123"

log:
  level: "debug"
  format: "text"
  output: "stdout"

auth:
  jwt:
    secret: "dev-secret-key"
    access_token_expire: "24h"
    refresh_token_expire: "168h"

测试环境配置​

# test.yaml
server:
  environment: "test"
  http:
    addr: "0.0.0.0:8000"
  grpc:
    addr: "0.0.0.0:9000"

data:
  database:
    host: "test-db.internal"
    port: 5432
    name: "jingyun_test"
    user: "test_user"
    password: "${TEST_DB_PASSWORD}"
    ssl_mode: "require"
  redis:
    addr: "test-redis.internal:6379"
    password: "${TEST_REDIS_PASSWORD}"

log:
  level: "info"
  format: "json"
  output: "stdout"

auth:
  jwt:
    secret: "${JWT_SECRET}"
    access_token_expire: "2h"
    refresh_token_expire: "168h"

生产环境配置​

# production.yaml
server:
  environment: "production"
  http:
    addr: "0.0.0.0:8000"
  grpc:
    addr: "0.0.0.0:9000"

data:
  database:
    host: "${DB_HOST}"
    port: ${DB_PORT}
    name: "${DB_NAME}"
    user: "${DB_USER}"
    password: "${DB_PASSWORD}"
    ssl_mode: "require"
    max_open_conns: 200
    max_idle_conns: 20
  redis:
    addr: "${REDIS_ADDR}"
    password: "${REDIS_PASSWORD}"
    pool_size: 200
    min_idle_conns: 20

log:
  level: "warn"
  format: "json"
  output: "stdout"

auth:
  jwt:
    secret: "${JWT_SECRET}"
    access_token_expire: "2h"
    refresh_token_expire: "168h"

配置最佳实践​

1. 配置管理原则​

  • 最小权限原则：只给服务必要的配置权限
  • 环境隔离原则：不同环境使用不同的配置
  • 密钥分离原则：敏感信息与普通配置分离
  • 版本控制原则：配置变更纳入版本控制

2. 安全配置实践​

  • 所有敏感配置使用环境变量
  • 定期轮换密钥和密码
  • 使用密钥管理服务
  • 配置文件不包含敏感信息

3. 运维配置实践​

  • 提供完整的配置文档
  • 支持配置验证和检查
  • 提供配置迁移工具
  • 监控配置变更和影响

4. 开发配置实践​

  • 提供本地开发配置模板
  • 支持配置热重载
  • 提供配置调试工具
  • 文档化所有配置项