ai_dianshang/ENVIRONMENTS.md

# 环境配置概览

本项目支持多个环境配置，适用于不同的开发和部署场景。

## 📋 环境列表

### 开发与测试环境

| 环境 | 标识 | 配置文件 | 用途 |
|------|------|---------|------|
| 开发环境 | `development` / `dev` | `config.dev.yaml` | 本地开发 |
| 测试环境 | `test` / `testing` | `config.test.yaml` | 功能测试 |

### 生产环境

| 环境 | 标识 | 配置文件 | 地域 | 用户群 |
|------|------|---------|------|--------|
| 生产-通用 | `production` / `prod` | `config.prod.yaml` | 通用 | 全球 |
| 生产-中国 | `production-cn` / `prod-cn` | `config.prod-cn.yaml` | 中国 | 中国大陆用户 |
| 生产-美国 | `production-us` / `prod-us` | `config.prod-us.yaml` | 美国 | 北美用户 |
| 生产-欧洲 | `production-eu` / `prod-eu` | `config.prod-eu.yaml` | 欧洲 | 欧洲用户 |

## 🚀 快速开始

### 后端启动

**使用脚本**（推荐）
```bash
# Windows
.\start-multi-env.bat

# Linux/Mac
chmod +x start-multi-env.sh
./start-multi-env.sh
```

**使用 Makefile**
```bash
make run-dev        # 开发环境
make run-test       # 测试环境
make run-prod-cn    # 中国区生产
make run-prod-us    # 美国区生产
make run-prod-eu    # 欧洲区生产
```

**直接运行**
```bash
# Windows PowerShell
$env:GO_ENV="prod-cn"; go run cmd/server/main.go

# Linux/Mac
GO_ENV=prod-cn go run cmd/server/main.go
```

### 前端配置

编辑 `miniprogram/config/index.js`：

```javascript
// 修改 CURRENT_ENV 变量
const CURRENT_ENV = 'production-cn';  // 或其他环境
```

## 🌍 各区域配置对比

### 服务器配置

| 配置项 | 中国区 | 美国区 | 欧洲区 |
|--------|--------|--------|--------|
| API域名 | api-cn.your-domain.com | api-us.your-domain.com | api-eu.your-domain.com |
| 端口 | 8060 | 8060 | 8060 |
| 模式 | release | release | release |

### 数据库配置

| 配置项 | 中国区 | 美国区 | 欧洲区 |
|--------|--------|--------|--------|
| 主机 | 8.149.233.36 | us-db.your-domain.com | eu-db.your-domain.com |
| 用户 | ai_dianshang | ai_dianshang_us | ai_dianshang_eu |
| 数据库 | ai_dianshang | ai_dianshang | ai_dianshang |

### 存储配置 (OSS)

| 配置项 | 中国区 | 美国区 | 欧洲区 |
|--------|--------|--------|--------|
| Endpoint | oss-cn-beijing.aliyuncs.com | oss-us-west-1.aliyuncs.com | oss-eu-central-1.aliyuncs.com |
| Bucket | bxmkb-beijing | your-us-bucket | your-eu-bucket |
| 地域 | 北京 | 美国西部 | 欧洲中部 |

## 📁 文件结构

```
dianshang/
├── server/
│   ├── configs/
│   │   ├── config.dev.yaml         # 开发环境
│   │   ├── config.test.yaml        # 测试环境
│   │   ├── config.prod.yaml        # 生产-通用
│   │   ├── config.prod-cn.yaml     # 生产-中国
│   │   ├── config.prod-us.yaml     # 生产-美国
│   │   └── config.prod-eu.yaml     # 生产-欧洲
│   ├── internal/config/config.go   # 配置加载逻辑
│   ├── 多环境配置说明.md            # 详细文档
│   └── docker-compose-multi-env.md # Docker部署文档
├── miniprogram/
│   ├── config/index.js             # 前端环境配置
│   └── utils/env-switcher.js       # 环境切换工具
├── start-multi-env.sh              # Linux/Mac启动脚本
├── start-multi-env.bat             # Windows启动脚本
└── Makefile                        # Make命令集
```

## 🔧 配置管理

### 环境变量优先级

系统按以下优先级检查环境变量：
1. `GO_ENV` （推荐）
2. `APP_ENV`
3. `ENVIRONMENT`

### 敏感信息管理

⚠️ **重要**: 不要将敏感信息提交到代码仓库

**推荐做法**:
1. 使用环境变量覆盖配置
2. 配置文件使用模板（.example）
3. 实际配置添加到 `.gitignore`
4. 生产环境使用密钥管理服务

### 配置覆盖

配置可以通过环境变量覆盖，格式：`大写_下划线分隔`

```bash
# 覆盖数据库密码
export DATABASE_PASSWORD=new-password

# 覆盖 JWT 密钥
export JWT_SECRET=new-secret-key
```

## 🐳 Docker 部署

### 中国区
```bash
docker run -e GO_ENV=prod-cn \
  -p 8060:8060 \
  -v $(pwd)/configs:/app/configs \
  your-image
```

### 美国区
```bash
docker run -e GO_ENV=prod-us \
  -p 8060:8060 \
  -v $(pwd)/configs:/app/configs \
  your-image
```

### 欧洲区
```bash
docker run -e GO_ENV=prod-eu \
  -p 8060:8060 \
  -v $(pwd)/configs:/app/configs \
  your-image
```

## 📚 相关文档

- [多环境配置详细说明](server/多环境配置说明.md) - 完整的配置指南
- [Docker多环境部署](server/docker-compose-multi-env.md) - Docker和K8s部署
- [基础配置说明](server/README_CONFIG.md) - 配置基础知识

## ⚙️ 添加新环境

如需添加新的区域（如亚太区），请参考以下步骤：

1. **创建配置文件**
   ```bash
   cp server/configs/config.prod-cn.yaml server/configs/config.prod-ap.yaml
   ```

2. **修改配置内容**
   - 数据库连接
   - API域名
   - OSS配置
   - 等其他区域特定配置

3. **更新代码** - 在 `config.go` 中添加环境映射

4. **更新前端** - 在 `config/index.js` 中添加环境配置

5. **更新文档** - 更新相关文档

详细步骤参见 [多环境配置说明.md](server/多环境配置说明.md#添加新区域)

## 🔍 故障排查

### 配置文件未加载

**检查项**:
- [ ] 环境变量设置正确
- [ ] 配置文件存在于 `configs/` 目录
- [ ] 文件名与环境匹配
- [ ] YAML语法正确

### 数据库连接失败

**检查项**:
- [ ] 数据库配置正确
- [ ] 网络连接正常
- [ ] 防火墙规则
- [ ] 数据库用户权限

### API调用失败

**检查项**:
- [ ] 前后端环境匹配
- [ ] API域名正确
- [ ] 服务已启动
- [ ] CORS配置

## 💡 最佳实践

1. **本地开发** - 使用 `development` 环境
2. **功能测试** - 使用 `test` 环境
3. **生产部署** - 根据用户地域选择对应的生产环境
4. **配置安全** - 敏感信息使用环境变量或密钥服务
5. **环境隔离** - 各环境使用独立的数据库和存储
6. **日志管理** - 不同环境使用不同的日志文件

## 📞 技术支持

如有问题，请查阅：
- [完整配置文档](server/多环境配置说明.md)
- [常见问题](server/多环境配置说明.md#常见问题)
- 项目 README.md