feat: 添加环境变量管理工具和部署配置改版
All checks were successful
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Successful in 5m33s
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:
108
README.md
108
README.md
@@ -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 @@ KeyAuth:Token 缺失
|
||||
|
||||
## 配置
|
||||
|
||||
### 环境特定配置
|
||||
### 嵌入式配置机制
|
||||
|
||||
设置 `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)
|
||||
|
||||
## 测试
|
||||
|
||||
### 运行所有测试
|
||||
|
||||
Reference in New Issue
Block a user