aaa46ef282
This commit implements a complete migration from JSON-based configuration to .env environment variables, providing better security and flexibility. Key Changes: - Add python-dotenv dependency for environment variable support - Create config/env_loader.py with type conversion utilities - Add from_env() class methods to all config dataclasses - Update ConfigLoader to prioritize environment variables - Add save_to_env() method for .env file management - Implement database connection factory pattern - Add base DAO and connection classes for better abstraction - Support both SQL Server and MySQL with unified interface - Create migration script (scripts/migrate_to_env.py) - Update GUI to read/write .env files - Add comprehensive migration documentation New Files: - config/env_loader.py - Environment variable loader - db/base_connection.py - Base database connection interface - db/base_dao.py - Base DAO with common utilities - db/connection_factory.py - Factory for creating connections - db/mysql_connection.py - MySQL-specific connection - db/sqlserver_connection.py - SQL Server-specific connection - db/table_name_converter.py - SQL dialect converter - scripts/migrate_to_env.py - Configuration migration tool - docs/ENV_MIGRATION.md - Complete migration guide - .env.example - Environment variable template Testing: - Verified MySQL connection (8.0.44) - Tested all DAO operations - Confirmed 150 tables accessible - Validated configuration loading Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
263 lines
6.6 KiB
Markdown
263 lines
6.6 KiB
Markdown
# .env 配置迁移指南
|
||
|
||
本文档说明如何将现有的 JSON 配置迁移到 .env 环境变量配置。
|
||
|
||
## 迁移原因
|
||
|
||
使用 .env 环境变量配置的优势：
|
||
|
||
1. **更好的安全性**: .env 文件不会被提交到版本控制（已添加到 .gitignore）
|
||
2. **更灵活的配置**: 可以在不同环境（开发、测试、生产）中使用不同的配置
|
||
3. **标准化**: 遵循 12-factor 应用配置最佳实践
|
||
4. **更简单**: 配置格式更简洁，易于维护
|
||
|
||
## 迁移步骤
|
||
|
||
### 方法 1: 从现有 JSON 配置迁移（推荐）
|
||
|
||
如果你已经有 `config/user_settings.json` 配置文件，可以使用迁移脚本自动转换：
|
||
|
||
```bash
|
||
python scripts/migrate_to_env.py migrate
|
||
```
|
||
|
||
该脚本会：
|
||
- 读取 `config/user_settings.json` 文件
|
||
- 创建 `.env` 文件
|
||
- 备份原 JSON 配置到 `config/user_settings.json.backup`
|
||
|
||
### 方法 2: 从模板创建新的配置
|
||
|
||
如果是首次配置，从模板创建：
|
||
|
||
```bash
|
||
python scripts/migrate_to_env.py from-example
|
||
```
|
||
|
||
该脚本会：
|
||
- 复制 `.env.example` 到 `.env`
|
||
- 提示你编辑 `.env` 文件填入实际配置
|
||
|
||
### 手动配置
|
||
|
||
1. 复制 `.env.example` 到 `.env`:
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
2. 编辑 `.env` 文件，填入实际的配置值：
|
||
|
||
```bash
|
||
# ERP 系统配置
|
||
ERP_URL=https://your-erp-system.com/
|
||
ERP_USERNAME=your_username
|
||
ERP_PASSWORD=your_password
|
||
|
||
# 数据库配置
|
||
DB_TYPE=sqlserver # 或 mysql
|
||
DB_SERVER=192.168.1.100
|
||
DB_NAME=YourDatabase
|
||
DB_USERNAME=your_db_username
|
||
DB_PASSWORD=your_db_password
|
||
```
|
||
|
||
## 配置验证
|
||
|
||
运行测试脚本验证配置是否正确加载：
|
||
|
||
```bash
|
||
python tests/test_env_config.py
|
||
```
|
||
|
||
## 环境变量参考
|
||
|
||
### ERP 系统配置
|
||
|
||
| 变量名 | 说明 | 默认值 |
|
||
|--------|------|--------|
|
||
| `ERP_URL` | ERP 系统地址 | `https://68.11.34.30:8082/` |
|
||
| `ERP_USERNAME` | ERP 用户名 | `BLDpengqiangqiang` |
|
||
| `ERP_PASSWORD` | ERP 密码 | (必填) |
|
||
| `ERP_HEADLESS` | 无头模式 | `true` |
|
||
| `ERP_IGNORE_HTTPS_ERRORS` | 忽略 HTTPS 错误 | `true` |
|
||
| `ERP_AUTO_CLOSE_BROWSER` | 自动关闭浏览器 | `true` |
|
||
|
||
### 数据库配置（SQL Server）
|
||
|
||
| 变量名 | 说明 | 默认值 |
|
||
|--------|------|--------|
|
||
| `DB_TYPE` | 数据库类型 | `sqlserver` |
|
||
| `DB_SERVER` | SQL Server 地址 | `192.168.110.114` |
|
||
| `DB_NAME` | 数据库名称 | `CompanyDB` |
|
||
| `DB_USERNAME` | 数据库用户名 | `peng` |
|
||
| `DB_PASSWORD` | 数据库密码 | (必填) |
|
||
| `DB_SQLSERVER_DRIVER` | ODBC 驱动 | `ODBC Driver 18 for SQL Server` |
|
||
| `DB_TRUST_SERVER_CERTIFICATE` | 信任服务器证书 | `yes` |
|
||
|
||
### 数据库配置（MySQL）
|
||
|
||
| 变量名 | 说明 | 默认值 |
|
||
|--------|------|--------|
|
||
| `DB_TYPE` | 数据库类型 | `mysql` |
|
||
| `DB_MYSQL_HOST` | MySQL 主机地址 | `192.168.31.83` |
|
||
| `DB_MYSQL_PORT` | MySQL 端口 | `3306` |
|
||
| `DB_MYSQL_CHARSET` | 字符集 | `utf8mb4` |
|
||
|
||
### 路径配置
|
||
|
||
| 变量名 | 说明 | 默认值 |
|
||
|--------|------|--------|
|
||
| `PATH_DATA_DIR` | 数据目录 | `D:/python/playwrite/data/` |
|
||
| `PATH_PRODUCTION_ID_FILE` | Production ID 文件名 | `ProductionID.txt` |
|
||
| `PATH_DEFAULT_OUTPUT` | 默认输出文件名 | `离散备料计划维护_合并.xlsx` |
|
||
| `PATH_VALIDATION_OUTPUT` | 校验输出文件名 | `物料状态校验结果.xlsx` |
|
||
|
||
### 数据提取配置
|
||
|
||
| 变量名 | 说明 | 默认值 |
|
||
|--------|------|--------|
|
||
| `EXTRACTION_BATCH_SIZE` | 批次大小 | `100` |
|
||
| `EXTRACTION_VERBOSE` | 详细日志 | `true` |
|
||
| `EXTRACTION_AUTO_CONVERT` | 自动转换 Excel | `true` |
|
||
| `EXTRACTION_MERGE_BATCHES` | 合并批次 | `true` |
|
||
| `EXTRACTION_ENABLE_DB_PERSISTENCE` | 保存到数据库 | `false` |
|
||
|
||
### 校验配置
|
||
|
||
| 变量名 | 说明 | 默认值 |
|
||
|--------|------|--------|
|
||
| `VALIDATION_DATA_SOURCE` | 数据源类型 | `database_full` |
|
||
| `VALIDATION_USE_DATABASE` | 使用数据库 | `true` |
|
||
| `VALIDATION_BATCH_SIZE` | 数据库批次大小 | `2000` |
|
||
| `VALIDATION_ENABLE_CRUD` | 启用 CRUD 操作 | `false` |
|
||
| `VALIDATION_DEFAULT_MANAGER` | 默认负责人 | (空) |
|
||
| `VALIDATION_MATCH_MODE` | 匹配模式 | `substring` |
|
||
|
||
## 切换数据库类型
|
||
|
||
要切换数据库类型，修改 `.env` 文件中的 `DB_TYPE` 变量：
|
||
|
||
### 切换到 MySQL
|
||
|
||
```bash
|
||
# 编辑 .env 文件
|
||
DB_TYPE=mysql
|
||
DB_NAME=BLD_DB
|
||
DB_USERNAME=remote_user
|
||
DB_PASSWORD=your_mysql_password
|
||
DB_MYSQL_HOST=192.168.31.83
|
||
DB_MYSQL_PORT=3306
|
||
```
|
||
|
||
### 切换到 SQL Server
|
||
|
||
```bash
|
||
# 编辑 .env 文件
|
||
DB_TYPE=sqlserver
|
||
DB_NAME=CompanyDB
|
||
DB_USERNAME=peng
|
||
DB_PASSWORD=your_sqlserver_password
|
||
DB_SERVER=192.168.110.114
|
||
```
|
||
|
||
## 在代码中使用配置
|
||
|
||
### 使用 ConfigLoader（推荐）
|
||
|
||
```python
|
||
from config.loader import ConfigLoader
|
||
|
||
# 加载配置（自动从环境变量）
|
||
config = ConfigLoader.load()
|
||
|
||
# 访问配置
|
||
erp_url = config.erp.url
|
||
db_type = config.database.db_type
|
||
```
|
||
|
||
### 直接从环境变量创建配置
|
||
|
||
```python
|
||
from config.schema import AppConfig
|
||
|
||
# 从环境变量创建配置
|
||
config = AppConfig.from_env()
|
||
```
|
||
|
||
### 使用 ConfigManager（GUI）
|
||
|
||
```python
|
||
from gui.config_manager import ConfigManager
|
||
|
||
# 创建配置管理器
|
||
config_manager = ConfigManager(use_env=True)
|
||
|
||
# 访问配置
|
||
erp_url = config_manager.get("erp.url")
|
||
```
|
||
|
||
## GUI 设置界面
|
||
|
||
GUI 设置界面已更新为读写 .env 文件。所有通过界面修改的配置会自动保存到 `.env` 文件。
|
||
|
||
## 回滚方案
|
||
|
||
如果迁移后出现问题，可以回滚：
|
||
|
||
1. 恢复 JSON 配置:
|
||
```bash
|
||
cp config/user_settings.json.backup config/user_settings.json
|
||
```
|
||
|
||
2. 删除 .env 文件:
|
||
```bash
|
||
rm .env
|
||
```
|
||
|
||
3. 修改代码使用 JSON 配置（需要修改 `ConfigManager` 初始化参数）:
|
||
```python
|
||
config_manager = ConfigManager(use_env=False)
|
||
```
|
||
|
||
## 安全注意事项
|
||
|
||
1. **永远不要将 .env 文件提交到版本控制**
|
||
- `.env` 已添加到 `.gitignore`
|
||
- 只提交 `.env.example` 模板文件
|
||
|
||
2. **保护敏感信息**
|
||
- 不要在代码中硬编码密码
|
||
- 使用强密码
|
||
- 定期更换密码
|
||
|
||
3. **文件权限**
|
||
- 确保 .env 文件只有你本人可读
|
||
- 在 Linux/Mac 上: `chmod 600 .env`
|
||
|
||
## 故障排除
|
||
|
||
### 配置未生效
|
||
|
||
1. 确认 `.env` 文件存在于项目根目录
|
||
2. 检查环境变量名称是否正确（区分大小写）
|
||
3. 重启应用程序以重新加载配置
|
||
|
||
### 迁移脚本错误
|
||
|
||
1. 检查 Python 版本（需要 Python 3.8+）
|
||
2. 确保已安装 `python-dotenv`: `pip install python-dotenv`
|
||
3. 查看错误信息并相应解决
|
||
|
||
### 数据库连接失败
|
||
|
||
1. 验证数据库配置是否正确
|
||
2. 检查数据库服务是否运行
|
||
3. 确认网络连接正常
|
||
4. 查看数据库驱动是否已安装
|
||
|
||
## 进一步阅读
|
||
|
||
- [12-factor App: Config](https://12factor.net/config)
|
||
- [python-dotenv 文档](https://github.com/theskumar/python-dotenv)
|