feat: 添加环境变量管理工具和部署配置改版
All checks were successful
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Successful in 5m33s

主要改动:
- 新增交互式环境配置脚本 (scripts/setup-env.sh)
- 新增本地启动快捷脚本 (scripts/run-local.sh)
- 新增环境变量模板文件 (.env.example)
- 部署模式改版:使用嵌入式配置 + 环境变量覆盖
- 添加对象存储功能支持
- 改进 IoT 卡片导入任务
- 优化 OpenAPI 文档生成
- 删除旧的配置文件,改用嵌入式默认配置
This commit is contained in:
2026-01-26 10:28:29 +08:00
parent 194078674a
commit 45aa7deb87
94 changed files with 6532 additions and 1967 deletions

108
README.md
View File

@@ -1,6 +1,6 @@
# 君鸿卡管系统 - Fiber 中间件集成
基于 Go + Fiber 框架的 HTTP 服务,集成了认证、限流、结构化日志和配置热重载功能。
基于 Go + Fiber 框架的 HTTP 服务,集成了认证、限流、结构化日志和嵌入式配置功能。
## 系统简介
@@ -186,7 +186,7 @@ default:
- **认证中间件**:基于 Redis 的 Token 认证
- **限流中间件**:基于 IP 的限流,支持可配置的限制和存储后端
- **结构化日志**:使用 Zap 的 JSON 日志和自动日志轮转
- **配置热重载**:运行时配置更新,无需重启服务
- **嵌入式配置**:配置嵌入二进制文件,通过环境变量覆盖,简化 Docker 部署
- **请求 ID 追踪**UUID 跨日志的请求追踪
- **Panic 恢复**:优雅的 panic 处理和堆栈跟踪日志
- **统一错误处理**:全局 ErrorHandler 统一处理所有 API 错误,返回一致的 JSON 格式包含错误码、消息、时间戳Panic 自动恢复防止服务崩溃;错误分类处理(客户端 4xx、服务端 5xx和日志级别控制敏感信息自动脱敏保护
@@ -199,6 +199,7 @@ default:
- **代理商体系**:层级管理和分佣结算
- **批量同步**:卡状态、实名状态、流量使用情况
- **分佣验证指引**:对代理分佣的冻结、解冻、提现校验流程进行了结构化说明与流程图,详见 [分佣逻辑正确与否验证](docs/优化说明/分佣逻辑正确与否验证.md)
- **对象存储**S3 兼容的对象存储服务集成(联通云 OSS支持预签名 URL 上传、文件下载、临时文件处理;用于 ICCID 批量导入、数据导出等场景;详见 [使用指南](docs/object-storage/使用指南.md) 和 [前端接入指南](docs/object-storage/前端接入指南.md)
## 用户体系设计
@@ -342,13 +343,12 @@ go run cmd/worker/main.go
**自定义配置**
可在 `configs/config.yaml`自定义默认管理员信息:
通过环境变量自定义默认管理员信息:
```yaml
default_admin:
username: "自定义用户名"
password: "自定义密码"
phone: "自定义手机号"
```bash
export JUNHONG_DEFAULT_ADMIN_USERNAME="自定义用户名"
export JUNHONG_DEFAULT_ADMIN_PASSWORD="自定义密码"
export JUNHONG_DEFAULT_ADMIN_PHONE="自定义手机号"
```
**注意事项**
@@ -389,8 +389,9 @@ junhong_cmp_fiber/
├── pkg/ # 公共工具库
│ ├── config/ # 配置管理
│ │ ├── config.go # 配置结构定义
│ │ ├── loader.go # 配置加载与验证
│ │ ── watcher.go # 配置热重载fsnotify
│ │ ├── loader.go # 配置加载(嵌入配置 + 环境变量覆盖)
│ │ ── embedded.go # go:embed 嵌入配置加载
│ │ └── defaults/config.yaml # 默认配置(嵌入二进制)
│ ├── logger/ # 日志基础设施
│ │ ├── logger.go # Zap 日志初始化
│ │ └── middleware.go # Fiber 日志中间件适配器
@@ -408,12 +409,6 @@ junhong_cmp_fiber/
│ │ └── redis.go # Redis 客户端初始化
│ └── queue/ # 队列封装Asynq
├── configs/ # 配置文件
│ ├── config.yaml # 默认配置
│ ├── config.dev.yaml # 开发环境
│ ├── config.staging.yaml # 预发布环境
│ └── config.prod.yaml # 生产环境
├── tests/
│ └── integration/ # 集成测试
│ ├── auth_test.go # 认证测试
@@ -630,48 +625,67 @@ KeyAuthToken 缺失
## 配置
### 环境特定配置
### 嵌入式配置机制
设置 `CONFIG_ENV` 环境变量以加载特定配置
系统使用 go:embed 将默认配置嵌入二进制文件,通过环境变量进行覆盖
- **默认配置**`pkg/config/defaults/config.yaml`(编译时嵌入)
- **环境变量前缀**`JUNHONG_`
- **格式转换**:配置路径中的 `.` 替换为 `_`
**环境变量覆盖示例**
| 配置项 | 环境变量 |
|-------|---------|
| `database.host` | `JUNHONG_DATABASE_HOST` |
| `redis.address` | `JUNHONG_REDIS_ADDRESS` |
| `jwt.secret_key` | `JUNHONG_JWT_SECRET_KEY` |
| `logging.level` | `JUNHONG_LOGGING_LEVEL` |
### 必填配置
以下配置项必须通过环境变量设置(无默认值或需要覆盖):
```bash
# 开发环境config.dev.yaml
export CONFIG_ENV=dev
# 数据库配置(必填
export JUNHONG_DATABASE_HOST=localhost
export JUNHONG_DATABASE_PORT=5432
export JUNHONG_DATABASE_USER=postgres
export JUNHONG_DATABASE_PASSWORD=your_password
export JUNHONG_DATABASE_DBNAME=junhong_cmp
# 预发布环境config.staging.yaml
export CONFIG_ENV=staging
# Redis 配置(必填
export JUNHONG_REDIS_ADDRESS=localhost
# 生产环境config.prod.yaml
export CONFIG_ENV=prod
# 默认配置config.yaml
# 不设置 CONFIG_ENV
# JWT 密钥(必填,生产环境必须修改
export JUNHONG_JWT_SECRET_KEY=your-secret-key-change-in-production
```
### 配置热重载
### Docker 部署
配置更改在 5 秒内自动检测并应用,无需重启服务器
Docker 部署使用纯环境变量配置,无需挂载配置文件
- **监控文件**:所有 `configs/*.yaml` 文件
- **检测**:使用 fsnotify 监视文件更改
- **验证**:应用前验证新配置
- **行为**
- 有效更改:立即应用,记录到 `logs/app.log`
- 无效更改:拒绝,服务器继续使用先前配置
- **原子性**:使用 `sync/atomic` 进行线程安全的配置更新
**示例**
```bash
# 在服务器运行时编辑配置
vim configs/config.yaml
# 将 logging.level 从 "info" 改为 "debug"
# 检查日志5 秒内)
tail -f logs/app.log | jq .
# {"level":"info","message":"配置文件已更改","file":"configs/config.yaml"}
# {"level":"info","message":"配置重新加载成功"}
```yaml
# docker-compose.prod.yml 示例
services:
api:
image: registry.boss160.cn/junhong/cmp-fiber-api:latest
environment:
- JUNHONG_DATABASE_HOST=db-host
- JUNHONG_DATABASE_PORT=5432
- JUNHONG_DATABASE_USER=postgres
- JUNHONG_DATABASE_PASSWORD=secret
- JUNHONG_DATABASE_DBNAME=junhong_cmp
- JUNHONG_REDIS_ADDRESS=redis
- JUNHONG_JWT_SECRET_KEY=production-secret
volumes:
- ./logs:/app/logs # 仅挂载日志目录
```
### 完整环境变量列表
详见 [环境变量配置文档](docs/environment-variables.md)
## 测试
### 运行所有测试