playwrite/docs/ENV_MIGRATION.md

.env 配置迁移指南

本文档说明如何将现有的 JSON 配置迁移到 .env 环境变量配置。

迁移原因

使用 .env 环境变量配置的优势：

1. 更好的安全性: .env 文件不会被提交到版本控制（已添加到 .gitignore）
2. 更灵活的配置: 可以在不同环境（开发、测试、生产）中使用不同的配置
3. 标准化: 遵循 12-factor 应用配置最佳实践
4. 更简单: 配置格式更简洁，易于维护

迁移步骤

方法 1: 从现有 JSON 配置迁移（推荐）

如果你已经有 config/user_settings.json 配置文件，可以使用迁移脚本自动转换：

python scripts/migrate_to_env.py migrate

该脚本会：

• 读取 config/user_settings.json 文件
• 创建 .env 文件
• 备份原 JSON 配置到 config/user_settings.json.backup

方法 2: 从模板创建新的配置

如果是首次配置，从模板创建：

python scripts/migrate_to_env.py from-example

该脚本会：

• 复制 .env.example 到 .env
• 提示你编辑 .env 文件填入实际配置

手动配置

1. 复制 .env.example 到 .env:

cp .env.example .env

2. 编辑 .env 文件，填入实际的配置值：

# 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

配置验证

运行测试脚本验证配置是否正确加载：

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

# 编辑 .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

# 编辑 .env 文件
DB_TYPE=sqlserver
DB_NAME=CompanyDB
DB_USERNAME=peng
DB_PASSWORD=your_sqlserver_password
DB_SERVER=192.168.110.114

在代码中使用配置

使用 ConfigLoader（推荐）

from config.loader import ConfigLoader

# 加载配置（自动从环境变量）
config = ConfigLoader.load()

# 访问配置
erp_url = config.erp.url
db_type = config.database.db_type

直接从环境变量创建配置

from config.schema import AppConfig

# 从环境变量创建配置
config = AppConfig.from_env()

使用 ConfigManager（GUI）

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 配置:

   cp config/user_settings.json.backup config/user_settings.json
   

2. 删除 .env 文件:

   rm .env
   

3. 修改代码使用 JSON 配置（需要修改 ConfigManager 初始化参数）:

   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
• python-dotenv 文档