spiderman/CONFIG_GUIDE.md

# 环境配置指南

## 📋 概述

本项目支持通过环境变量和配置文件来管理应用程序配置。配置系统具有以下特性：

- 🔧 支持从 `.env` 和 `config.env` 文件加载配置
- 🌍 环境变量优先级高于配置文件
- 🎯 针对开发和生产环境的不同配置
- 📚 完整的配置文档和示例

## 🚀 快速开始

### 1. 设置配置文件

```bash
# 复制示例配置文件
cp config.env.example config.env

# 或使用Makefile
make env-setup
```

### 2. 编辑配置

编辑 `config.env` 文件，根据您的环境调整配置：

```bash
# 服务器配置
PORT=8080

# Fabric配置
MSP_ID=Org1MSP
CRYPTO_PATH=../../test-network/organizations/peerOrganizations/org1.example.com
CHANNEL_NAME=mychannel
CHAINCODE_NAME=basic

# 日志配置
LOG_LEVEL=info
LOG_FORMAT=text

# 环境配置
ENVIRONMENT=development
```

### 3. 运行应用

```bash
# 开发环境
make run-dev

# 生产环境
make run-prod

# 或直接运行
make run
```

## 📖 配置选项

### 服务器配置

| 变量 | 默认值 | 描述 |
|------|--------|------|
| `PORT` | `8080` | HTTP服务器端口 |

### Hyperledger Fabric配置

| 变量 | 默认值 | 描述 |
|------|--------|------|
| `MSP_ID` | `Org1MSP` | MSP身份ID |
| `CRYPTO_PATH` | `../../test-network/organizations/...` | 加密材料基础路径 |
| `CERT_PATH` | `{CRYPTO_PATH}/users/.../signcerts` | 证书路径 |
| `KEY_PATH` | `{CRYPTO_PATH}/users/.../keystore` | 私钥路径 |
| `TLS_CERT_PATH` | `{CRYPTO_PATH}/peers/.../tls/ca.crt` | TLS证书路径 |
| `PEER_ENDPOINT` | `dns:///localhost:7051` | Peer节点gRPC端点 |
| `GATEWAY_PEER` | `peer0.org1.example.com` | 网关Peer名称 |
| `CHANNEL_NAME` | `mychannel` | 区块链通道名称 |
| `CHAINCODE_NAME` | `basic` | 链码名称 |

### 日志配置

| 变量 | 默认值 | 可选值 | 描述 |
|------|--------|--------|------|
| `LOG_LEVEL` | `info` | `panic`, `fatal`, `error`, `warn`, `info`, `debug`, `trace` | 日志级别 |
| `LOG_FORMAT` | `text` | `text`, `json` | 日志格式 |

### 环境配置

| 变量 | 默认值 | 可选值 | 描述 |
|------|--------|--------|------|
| `ENVIRONMENT` | `development` | `development`, `production` | 运行环境 |
| `API_TIMEOUT` | `30` | 数字 | API超时时间（秒） |
| `DB_TIMEOUT` | `10` | 数字 | 数据库超时时间（秒） |

## 🔧 配置优先级

配置加载优先级（从高到低）：

1. **环境变量** - 系统环境变量
2. **config.env** - 项目配置文件
3. **默认值** - 代码中定义的默认值

## 💡 使用示例

### 开发环境配置

```bash
# config.env for development
ENVIRONMENT=development
LOG_LEVEL=debug
LOG_FORMAT=text
PORT=8080
```

### 生产环境配置

```bash
# config.env for production
ENVIRONMENT=production
LOG_LEVEL=warn
LOG_FORMAT=json
PORT=80
```

### Docker环境配置

```bash
# 通过环境变量传递
docker run -p 8080:8080 \
  -e ENVIRONMENT=production \
  -e LOG_FORMAT=json \
  -e LOG_LEVEL=info \
  spiderman
```

## 🎯 环境特定功能

### 开发环境
- ✅ Swagger文档可用 (`/swagger/`)
- 📊 详细的调试日志
- 🔧 热重载支持

### 生产环境
- 🚫 Swagger文档关闭
- 📈 JSON格式日志
- ⚡ 优化的性能设置

## 🛠️ Makefile命令

```bash
# 环境配置
make env-setup          # 设置配置文件
make show-config        # 显示当前配置

# 运行命令
make run                # 使用配置文件运行
make run-dev            # 开发环境运行
make run-prod           # 生产环境运行

# Docker命令
make docker-run         # Docker运行
make docker-run-dev     # Docker开发环境运行
```

## 🔍 配置验证

检查当前配置：

```bash
make show-config
```

运行时配置验证：

```bash
# 启动应用时会显示加载的配置
make run-dev
```

## 🚨 安全注意事项

1. **不要提交包含敏感信息的配置文件到版本控制**
2. **生产环境使用环境变量而不是配置文件**
3. **定期轮换证书和密钥**
4. **使用适当的文件权限保护配置文件**

## 🔧 故障排除

### 常见问题

**Q: 配置文件没有生效？**
A: 检查文件名是否正确（`config.env`），环境变量优先级更高

**Q: Fabric连接失败？**
A: 检查 `CRYPTO_PATH` 和相关证书路径是否正确

**Q: 日志级别没有改变？**
A: 确保 `LOG_LEVEL` 值正确，重启应用程序

### 调试配置

启用调试模式查看配置加载过程：

```bash
LOG_LEVEL=debug make run
```

## 📚 参考资料

- [Go环境变量最佳实践](https://12factor.net/config)
- [Hyperledger Fabric配置文档](https://hyperledger-fabric.readthedocs.io/)
- [项目结构说明](./PROJECT_STRUCTURE.md)