feat: 添加环境变量管理工具和部署配置改版

主要改动： - 新增交互式环境配置脚本 (scripts/setup-env.sh) - 新增本地启动快捷脚本 (scripts/run-local.sh) - 新增环境变量模板文件 (.env.example) - 部署模式改版：使用嵌入式配置 + 环境变量覆盖 - 添加对象存储功能支持 - 改进 IoT 卡片导入任务 - 优化 OpenAPI 文档生成 - 删除旧的配置文件，改用嵌入式默认配置
2026-01-26 10:28:29 +08:00
parent 194078674a
commit 45aa7deb87
94 changed files with 6532 additions and 1967 deletions
--- a/docs/environment-variables.md
+++ b/docs/environment-variables.md
@@ -0,0 +1,212 @@
+# 环境变量配置文档
+
+## 概述
+
+君鸿卡管系统使用嵌入式配置机制，默认配置编译在二进制文件中，通过环境变量进行覆盖。
+
+**环境变量前缀**: `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_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
+```