csxj2026/junhong_cmp_fiber
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
Files
main
junhong_cmp_fiber/docs/environment-variables.md
huang bf591095a2 微信相关能力
2026-01-30 17:25:30 +08:00

247 lines
9.0 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 环境变量配置文档
## 概述
君鸿卡管系统使用嵌入式配置机制，默认配置编译在二进制文件中，通过环境变量进行覆盖。
**环境变量前缀**: `JUNHONG_`
**格式规则**: 配置路径中的 `.` 替换为 `_`，全部大写
## 必填配置
以下配置没有合理的默认值，必须通过环境变量设置：
### 数据库配置
| 环境变量 | 说明 | 示例 |
|---------|------|------|
| `JUNHONG_DATABASE_HOST` | 数据库主机地址 | `localhost` |
| `JUNHONG_DATABASE_PORT` | 数据库端口 | `5432` |
| `JUNHONG_DATABASE_USER` | 数据库用户名 | `postgres` |
| `JUNHONG_DATABASE_PASSWORD` | 数据库密码 | `your_password` |
| `JUNHONG_DATABASE_DBNAME` | 数据库名称 | `junhong_cmp` |
### Redis 配置
| 环境变量 | 说明 | 示例 |
|---------|------|------|
| `JUNHONG_REDIS_ADDRESS` | Redis 主机地址 | `localhost` |
### JWT 配置
| 环境变量 | 说明 | 示例 |
|---------|------|------|
| `JUNHONG_JWT_SECRET_KEY` | JWT 签名密钥（生产环境必须修改） | `your-secret-key` |
### 微信配置
#### 微信公众号
| 环境变量 | 说明 | 示例 |
|---------|------|------|
| `JUNHONG_WECHAT_OFFICIAL_ACCOUNT_APP_ID` | 公众号 AppID（必填） | `wxabcdef1234567890` |
| `JUNHONG_WECHAT_OFFICIAL_ACCOUNT_APP_SECRET` | 公众号 AppSecret（必填） | `abcdef1234567890` |
| `JUNHONG_WECHAT_OFFICIAL_ACCOUNT_TOKEN` | 服务器配置Token（可选） | `your_token` |
| `JUNHONG_WECHAT_OFFICIAL_ACCOUNT_AES_KEY` | 消息加解密Key（可选） | `` |
| `JUNHONG_WECHAT_OFFICIAL_ACCOUNT_OAUTH_REDIRECT_URL` | OAuth回调URL（可选） | `https://your-domain.com/callback` |
#### 微信支付
| 环境变量 | 说明 | 示例 |
|---------|------|------|
| `JUNHONG_WECHAT_PAYMENT_APP_ID` | 支付 AppID（必填，通常与公众号相同） | `wxabcdef1234567890` |
| `JUNHONG_WECHAT_PAYMENT_MCH_ID` | 商户号（必填） | `1234567890` |
| `JUNHONG_WECHAT_PAYMENT_API_V3_KEY` | APIv3 密钥（必填，32位字符串） | `your_apiv3_key_32_chars_here` |
| `JUNHONG_WECHAT_PAYMENT_API_V2_KEY` | APIv2 密钥（可选，部分接口需要） | `` |
| `JUNHONG_WECHAT_PAYMENT_CERT_PATH` | 商户证书路径（必填） | `/app/certs/apiclient_cert.pem` |
| `JUNHONG_WECHAT_PAYMENT_KEY_PATH` | 商户私钥路径（必填） | `/app/certs/apiclient_key.pem` |
| `JUNHONG_WECHAT_PAYMENT_SERIAL_NO` | 证书序列号（必填） | `1234567890ABCDEF` |
| `JUNHONG_WECHAT_PAYMENT_NOTIFY_URL` | 支付回调URL（必填） | `https://api.your-domain.com/api/callback/wechat-pay` |
| `JUNHONG_WECHAT_PAYMENT_HTTP_DEBUG` | HTTP调试日志（可选） | `false` |
| `JUNHONG_WECHAT_PAYMENT_TIMEOUT` | HTTP请求超时（可选） | `30s` |
**配置说明**：
- 微信公众号和支付配置缺失时，服务启动会失败（FATAL 错误）
- 证书文件必须可读（权限 600 或 644）
- APIv3 密钥必须是 32 位字符串
- 证书序列号可通过 `openssl x509 -in apiclient_cert.pem -noout -serial` 获取
- 详细配置指南参见 [微信集成使用指南](wechat-integration/使用指南.md)
## 可选配置
以下配置有合理的默认值，可按需覆盖：
### 服务器配置
| 环境变量 | 默认值 | 说明 |
|---------|--------|------|
| `JUNHONG_SERVER_ADDRESS` | `:3000` | 服务监听地址 |
| `JUNHONG_SERVER_READ_TIMEOUT` | `30s` | 读取超时时间 |
| `JUNHONG_SERVER_WRITE_TIMEOUT` | `30s` | 写入超时时间 |
| `JUNHONG_SERVER_SHUTDOWN_TIMEOUT` | `30s` | 优雅关闭超时 |
| `JUNHONG_SERVER_PREFORK` | `false` | 是否启用预分叉模式 |
### 数据库连接池
| 环境变量 | 默认值 | 说明 |
|---------|--------|------|
| `JUNHONG_DATABASE_SSLMODE` | `disable` | SSL 模式 |
| `JUNHONG_DATABASE_MAX_OPEN_CONNS` | `25` | 最大打开连接数 |
| `JUNHONG_DATABASE_MAX_IDLE_CONNS` | `10` | 最大空闲连接数 |
| `JUNHONG_DATABASE_CONN_MAX_LIFETIME` | `1h` | 连接最大生命周期 |
### Redis 配置
| 环境变量 | 默认值 | 说明 |
|---------|--------|------|
| `JUNHONG_REDIS_PORT` | `6379` | Redis 端口 |
| `JUNHONG_REDIS_PASSWORD` | `""` | Redis 密码 |
| `JUNHONG_REDIS_DB` | `0` | Redis 数据库编号 |
| `JUNHONG_REDIS_POOL_SIZE` | `100` | 连接池大小 |
| `JUNHONG_REDIS_MIN_IDLE_CONNS` | `10` | 最小空闲连接数 |
| `JUNHONG_REDIS_DIAL_TIMEOUT` | `5s` | 连接超时 |
| `JUNHONG_REDIS_READ_TIMEOUT` | `3s` | 读取超时 |
| `JUNHONG_REDIS_WRITE_TIMEOUT` | `3s` | 写入超时 |
### 日志配置
| 环境变量 | 默认值 | 说明 |
|---------|--------|------|
| `JUNHONG_LOGGING_LEVEL` | `info` | 日志级别 (debug/info/warn/error) |
| `JUNHONG_LOGGING_DEVELOPMENT` | `false` | 开发模式（启用彩色输出） |
| `JUNHONG_LOGGING_APP_LOG_FILENAME` | `logs/app.log` | 应用日志文件路径 |
| `JUNHONG_LOGGING_APP_LOG_MAX_SIZE` | `100` | 日志文件最大大小 (MB) |
| `JUNHONG_LOGGING_APP_LOG_MAX_BACKUPS` | `7` | 最大备份文件数 |
| `JUNHONG_LOGGING_APP_LOG_MAX_AGE` | `30` | 日志保留天数 |
| `JUNHONG_LOGGING_APP_LOG_COMPRESS` | `true` | 是否压缩旧日志 |
| `JUNHONG_LOGGING_ACCESS_LOG_FILENAME` | `logs/access.log` | 访问日志文件路径 |
### JWT 配置
| 环境变量 | 默认值 | 说明 |
|---------|--------|------|
| `JUNHONG_JWT_TOKEN_DURATION` | `24h` | Token 有效期 |
| `JUNHONG_JWT_ACCESS_TOKEN_TTL` | `24h` | Access Token TTL |
| `JUNHONG_JWT_REFRESH_TOKEN_TTL` | `168h` | Refresh Token TTL (7天) |
### 队列配置
| 环境变量 | 默认值 | 说明 |
|---------|--------|------|
| `JUNHONG_QUEUE_CONCURRENCY` | `10` | 并发 Worker 数量 |
| `JUNHONG_QUEUE_RETRY_MAX` | `3` | 最大重试次数 |
| `JUNHONG_QUEUE_TIMEOUT` | `30m` | 任务超时时间 |
### 限流中间件
| 环境变量 | 默认值 | 说明 |
|---------|--------|------|
| `JUNHONG_MIDDLEWARE_ENABLE_RATE_LIMITER` | `false` | 启用限流 |
| `JUNHONG_MIDDLEWARE_RATE_LIMITER_MAX` | `100` | 最大请求数 |
| `JUNHONG_MIDDLEWARE_RATE_LIMITER_EXPIRATION` | `1m` | 时间窗口 |
| `JUNHONG_MIDDLEWARE_RATE_LIMITER_STORAGE` | `memory` | 存储后端 (memory/redis) |
### 对象存储配置
| 环境变量 | 默认值 | 说明 |
|---------|--------|------|
| `JUNHONG_STORAGE_PROVIDER` | `""` | 存储提供商 (s3) |
| `JUNHONG_STORAGE_TEMP_DIR` | `/tmp/junhong` | 临时文件目录 |
| `JUNHONG_STORAGE_S3_ENDPOINT` | `""` | S3 端点 |
| `JUNHONG_STORAGE_S3_REGION` | `""` | S3 区域 |
| `JUNHONG_STORAGE_S3_BUCKET` | `""` | S3 存储桶 |
| `JUNHONG_STORAGE_S3_ACCESS_KEY_ID` | `""` | S3 访问密钥 ID |
| `JUNHONG_STORAGE_S3_SECRET_ACCESS_KEY` | `""` | S3 访问密钥 |
| `JUNHONG_STORAGE_S3_USE_SSL` | `true` | 是否使用 SSL |
| `JUNHONG_STORAGE_S3_PATH_STYLE` | `true` | 是否使用路径风格 |
| `JUNHONG_STORAGE_PRESIGN_UPLOAD_EXPIRES` | `1h` | 预签名上传 URL 有效期 |
| `JUNHONG_STORAGE_PRESIGN_DOWNLOAD_EXPIRES` | `1h` | 预签名下载 URL 有效期 |
### 短信配置
| 环境变量 | 默认值 | 说明 |
|---------|--------|------|
| `JUNHONG_SMS_GATEWAY_URL` | `""` | 短信网关 URL |
| `JUNHONG_SMS_USERNAME` | `""` | 短信账号 |
| `JUNHONG_SMS_PASSWORD` | `""` | 短信密码 |
| `JUNHONG_SMS_SIGNATURE` | `""` | 短信签名 |
| `JUNHONG_SMS_TIMEOUT` | `10s` | 请求超时 |
### 默认管理员
| 环境变量 | 默认值 | 说明 |
|---------|--------|------|
| `JUNHONG_DEFAULT_ADMIN_USERNAME` | `admin` | 默认管理员用户名 |
| `JUNHONG_DEFAULT_ADMIN_PASSWORD` | `Admin@123456` | 默认管理员密码 |
| `JUNHONG_DEFAULT_ADMIN_PHONE` | `13800000000` | 默认管理员手机号 |
## Docker Compose 示例
```yaml
version: '3.8'
services:
api:
image: registry.boss160.cn/junhong/cmp-fiber-api:latest
environment:
- JUNHONG_DATABASE_HOST=postgres
- JUNHONG_DATABASE_PORT=5432
- JUNHONG_DATABASE_USER=junhong
- JUNHONG_DATABASE_PASSWORD=secret123
- JUNHONG_DATABASE_DBNAME=junhong_cmp
- JUNHONG_REDIS_ADDRESS=redis
- JUNHONG_JWT_SECRET_KEY=your-production-secret-key
- JUNHONG_LOGGING_LEVEL=info
volumes:
- ./logs:/app/logs
ports:
- "3000:3000"
worker:
image: registry.boss160.cn/junhong/cmp-fiber-worker:latest
environment:
- JUNHONG_DATABASE_HOST=postgres
- JUNHONG_DATABASE_PORT=5432
- JUNHONG_DATABASE_USER=junhong
- JUNHONG_DATABASE_PASSWORD=secret123
- JUNHONG_DATABASE_DBNAME=junhong_cmp
- JUNHONG_REDIS_ADDRESS=redis
- JUNHONG_JWT_SECRET_KEY=your-production-secret-key
volumes:
- ./logs:/app/logs
postgres:
image: postgres:14
environment:
- POSTGRES_USER=junhong
- POSTGRES_PASSWORD=secret123
- POSTGRES_DB=junhong_cmp
redis:
image: redis:6
```
## 本地开发
本地开发可以创建 `.env` 文件（不要提交到 Git）：
```bash
# .env
JUNHONG_DATABASE_HOST=localhost
JUNHONG_DATABASE_PORT=5432
JUNHONG_DATABASE_USER=postgres
JUNHONG_DATABASE_PASSWORD=postgres
JUNHONG_DATABASE_DBNAME=junhong_cmp_dev
JUNHONG_REDIS_ADDRESS=localhost
JUNHONG_JWT_SECRET_KEY=dev-secret-key
JUNHONG_LOGGING_LEVEL=debug
JUNHONG_LOGGING_DEVELOPMENT=true
```
然后使用 `source .env` 加载环境变量后运行：
```bash
source .env
go run cmd/api/main.go
```
Reference in New Issue View Git Blame Copy Permalink