first commit

2025-12-19 22:36:48 +08:00
commit 6802624e59
185 changed files with 43430 additions and 0 deletions
--- a/go_backend/ENV_CONFIG_GUIDE.md
+++ b/go_backend/ENV_CONFIG_GUIDE.md
@@ -0,0 +1,264 @@
+# 环境变量配置指南
+
+## 概述
+
+Go 服务支持通过**环境变量**来确定配置,优先级为:
+
+```
+环境变量 > 配置文件 > 默认值
+```
+
+## 1. 环境选择
+
+### 方式一:环境变量 `APP_ENV`(推荐)
+```bash
+# Windows PowerShell
+$env:APP_ENV="prod"
+.\start.bat
+
+# Linux/Mac
+export APP_ENV=prod
+./start.sh
+
+# Docker
+docker run -e APP_ENV=prod ...
+```
+
+### 方式二:命令行参数
+```bash
+go run main.go -env=prod
+```
+
+### 方式三:默认值
+不设置任何参数时,默认使用 `dev` 环境
+
+---
+
+## 2. 支持的环境变量
+
+### 服务器配置
+| 环境变量 | 配置项 | 说明 | 示例 |
+|---------|--------|------|------|
+| `SERVER_PORT` | server.port | 服务端口 | 8080 |
+| `SERVER_MODE` | server.mode | 运行模式 | release |
+
+### 数据库配置
+| 环境变量 | 配置项 | 说明 | 示例 |
+|---------|--------|------|------|
+| `DB_HOST` | database.host | 数据库地址 | localhost |
+| `DB_PORT` | database.port | 数据库端口 | 3306 |
+| `DB_USERNAME` | database.username | 用户名 | root |
+| `DB_PASSWORD` | database.password | 密码 | your_password |
+| `DB_NAME` | database.dbname | 数据库名 | ai_wht |
+| `DB_CHARSET` | database.charset | 字符集 | utf8mb4 |
+
+### JWT 配置
+| 环境变量 | 配置项 | 说明 | 示例 |
+|---------|--------|------|------|
+| `JWT_SECRET` | jwt.secret | JWT 密钥 | your_secret_key |
+| `JWT_EXPIRE_HOURS` | jwt.expire_hours | 过期时间(小时) | 168 |
+
+### 微信配置
+| 环境变量 | 配置项 | 说明 | 示例 |
+|---------|--------|------|------|
+| `WECHAT_APP_ID` | wechat.app_id | 微信 AppID | wx1234567890 |
+| `WECHAT_APP_SECRET` | wechat.app_secret | 微信 AppSecret | your_secret |
+
+### 小红书配置
+| 环境变量 | 配置项 | 说明 | 示例 |
+|---------|--------|------|------|
+| `XHS_PYTHON_SERVICE_URL` | xhs.python_service_url | Python服务地址 | http://localhost:8000 |
+
+---
+
+## 3. 使用场景
+
+### 场景一:本地开发(覆盖数据库密码)
+```bash
+# Windows
+$env:DB_PASSWORD="local_password"
+go run main.go
+
+# Linux/Mac
+export DB_PASSWORD=local_password
+go run main.go
+```
+
+### 场景二:生产部署
+```bash
+# 设置生产环境
+$env:APP_ENV="prod"
+$env:DB_HOST="prod-db.example.com"
+$env:DB_PASSWORD="prod_secure_password"
+$env:JWT_SECRET="prod_jwt_secret_key"
+$env:WECHAT_APP_ID="wx_prod_appid"
+$env:WECHAT_APP_SECRET="wx_prod_secret"
+
+.\start.bat
+```
+
+### 场景三:Docker 部署
+```dockerfile
+# Dockerfile
+FROM golang:1.21-alpine
+
+WORKDIR /app
+COPY . .
+
+RUN go build -o main .
+
+# 设置环境变量
+ENV APP_ENV=prod
+ENV SERVER_PORT=8080
+ENV DB_HOST=mysql-server
+
+CMD ["./main"]
+```
+
+```bash
+# docker-compose.yml
+version: '3.8'
+services:
+  go-backend:
+    build: .
+    environment:
+      - APP_ENV=prod
+      - DB_HOST=mysql
+      - DB_PASSWORD=${DB_PASSWORD}
+      - WECHAT_APP_ID=${WECHAT_APP_ID}
+      - WECHAT_APP_SECRET=${WECHAT_APP_SECRET}
+    ports:
+      - "8080:8080"
+```
+
+### 场景四:CI/CD 流水线
+```yaml
+# GitHub Actions
+env:
+  APP_ENV: prod
+  DB_HOST: ${{ secrets.DB_HOST }}
+  DB_PASSWORD: ${{ secrets.DB_PASSWORD }}
+  JWT_SECRET: ${{ secrets.JWT_SECRET }}
+  WECHAT_APP_ID: ${{ secrets.WECHAT_APP_ID }}
+  WECHAT_APP_SECRET: ${{ secrets.WECHAT_APP_SECRET }}
+```
+
+---
+
+## 4. 配置优先级示例
+
+假设 `config.prod.yaml` 中配置:
+```yaml
+database:
+  host: localhost
+  port: 3306
+  password: file_password
+```
+
+运行时设置环境变量:
+```bash
+$env:DB_HOST="prod-server.com"
+$env:DB_PASSWORD="env_password"
+```
+
+**最终生效的配置:**
+```
+host: prod-server.com         # 来自环境变量 DB_HOST
+port: 3306                    # 来自配置文件
+password: env_password        # 来自环境变量 DB_PASSWORD
+```
+
+---
+
+## 5. 查看当前配置
+
+启动服务时,会在日志中输出:
+```
+2024/12/15 14:45:00 从环境变量 APP_ENV 读取环境: prod
+2024/12/15 14:45:00 配置加载成功: prod 环境
+2024/12/15 14:45:00 数据库配置: root@prod-server.com:3306/ai_wht
+```
+
+---
+
+## 6. 安全建议
+
+1. **敏感信息不要写入配置文件**,使用环境变量:
+   - `DB_PASSWORD`
+   - `JWT_SECRET`
+   - `WECHAT_APP_SECRET`
+
+2. **生产环境必须覆盖的环境变量**:
+   ```bash
+   APP_ENV=prod
+   DB_PASSWORD=<secure_password>
+   JWT_SECRET=<random_secret_key>
+   WECHAT_APP_SECRET=<wechat_secret>
+   ```
+
+3. **使用密钥管理工具**(可选):
+   - Azure Key Vault
+   - AWS Secrets Manager
+   - HashiCorp Vault
+
+---
+
+## 7. 快速启动脚本
+
+### Windows (start_with_env.bat)
+```bat
+@echo off
+set APP_ENV=prod
+set DB_HOST=localhost
+set DB_PASSWORD=your_password
+set JWT_SECRET=your_jwt_secret
+set WECHAT_APP_ID=your_appid
+set WECHAT_APP_SECRET=your_secret
+
+go run main.go
+```
+
+### Linux/Mac (start_with_env.sh)
+```bash
+#!/bin/bash
+export APP_ENV=prod
+export DB_HOST=localhost
+export DB_PASSWORD=your_password
+export JWT_SECRET=your_jwt_secret
+export WECHAT_APP_ID=your_appid
+export WECHAT_APP_SECRET=your_secret
+
+go run main.go
+```
+
+---
+
+## 8. 常见问题
+
+### Q: 环境变量没生效?
+**A:** 检查环境变量名称是否正确,区分大小写。
+
+### Q: 如何查看所有环境变量?
+**A:**
+```bash
+# Windows
+Get-ChildItem Env:
+
+# Linux/Mac
+printenv
+```
+
+### Q: 如何临时设置环境变量?
+**A:**
+```bash
+# Windows - 当前会话有效
+$env:DB_PASSWORD="temp_password"
+
+# Linux/Mac - 当前会话有效
+export DB_PASSWORD=temp_password
+```
+
+### Q: 如何永久设置环境变量?
+**A:**
+- Windows: 系统设置 → 高级系统设置 → 环境变量
+- Linux/Mac: 添加到 `~/.bashrc` 或 `~/.zshrc`