🚀 DMS 环境配置使用指南

目录结构

C:\DMS\
├── .env                          # 当前使用的配置文件（不要提交到Git）
├── .env.development              # 开发环境配置模板（可以提交到Git）
├── .env.production.template      # 生产环境配置模板（可以提交到Git）
├── config/
│   └── env.py                    # 环境变量加载和解析逻辑
├── application/
│   └── settings.py               # Django设置（从config.env导入配置）
├── switch_env.ps1                # 环境切换脚本
├── validate_config.py            # 配置验证脚本
└── .gitignore                    # Git忽略规则

快速开始

1️⃣ 切换到开发环境

# 在项目根目录执行
.\switch_env.ps1 development

========================================
  DMS Environment Switch Tool
========================================

[OK] Backed up current config: C:\DMS\.env.backup.20260416_151622
[OK] Switched to: Development Environment
[INFO] Config file: C:\DMS\.env

[WARNING] Please restart Django service to apply changes

Verify configuration:
   python validate_config.py

2️⃣ 准备生产环境

# 复制生产环境模板
.\switch_env.ps1 production

# 编辑 .env 文件，修改所有敏感信息
notepad .env

========================================
  DMS Environment Switch Tool
========================================

[OK] Backed up current config: C:\DMS\.env.backup.20260416_151622
[OK] Switched to: Production Environment (Template)
[INFO] Config file: C:\DMS\.env

[WARNING] Important Notes:
   1. Please edit .env file and modify all sensitive information
   2. Generate strong keys for DJANGO_SECRET_KEY and JWT_SECRET_KEY
   3. Update database configuration with production values

Commands to generate strong keys:
   Django: python -c "from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())"
   JWT:    python -c "import secrets; print(secrets.token_urlsafe(43))"

[WARNING] Please restart Django service to apply changes

Verify configuration:
   python validate_config.py

生成强密钥的命令：

# Django SECRET_KEY
python -c "from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())"

# JWT SECRET_KEY
python -c "import secrets; print(secrets.token_urlsafe(43))"

3️⃣ 验证配置

python validate_config.py

配置文件说明

.env - 当前使用的配置

这是实际被系统读取的配置文件。

.env.development - 开发环境模板

开发环境的推荐配置：

• DJANGO_DEBUG=true - 显示详细错误信息
• ENABLE_MAIL_ALARM=false - 关闭邮件报警
• ENABLE_SMS_ALARM=false - 关闭短信报警
• DB_NAME=dms_dev - 使用独立的开发数据库

.env.production.template - 生产环境模板

生产环境的配置模板（需要修改后才能使用）：

• DJANGO_DEBUG=false - 隐藏敏感信息
• DJANGO_ALLOWED_HOSTS=your-domain.com - 明确指定域名
• ENABLE_MAIL_ALARM=true - 启用报警
• DB_USER=dms_user - 使用专用数据库用户

配置项详解

基础配置

数据库配置

应用配置

报警配置

环境切换流程

场景1：从开发切换到生产

.\switch_env.ps1 production

notepad .env

python validate_config.py

场景2：从生产切换到开发

.\switch_env.ps1 development

python validate_config.py

安全注意事项

✅ 应该做的

1. 保护 .env 文件

• 不要通过邮件、聊天工具发送
• 不要上传到公开代码仓库
• 使用文件权限限制访问

2. 使用强密钥和密码

# 生成 Django SECRET_KEY
python -c "from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())"

# 生成 JWT SECRET_KEY
python -c "import secrets; print(secrets.token_urlsafe(43))"

# 生成随机密码（16字符）
python -c "import secrets; import string; chars = string.ascii_letters + string.digits + '!@#$%^&*'; print(''.join(secrets.choice(chars) for _ in range(16)))"

3. 定期轮换密钥

• 建议每 3-6 个月更换一次密钥
• 员工离职后立即更换

4. 使用不同的数据库用户

• 开发环境：可以用 root（仅限本地）
• 生产环境：创建专用用户，只授予必要权限

❌ 不应该做的

1. 不要硬编码敏感信息

# ❌ 错误
DATABASE_PASSWORD = "my_password_123"

# ✅ 正确
DATABASE_PASSWORD = os.environ.get('DB_PASSWORD', 'default')

2. 不要在生产环境使用 DEBUG=True

• 会泄露敏感信息
• 性能较差

3. 不要在生产环境使用 ALLOWED_HOSTS='*'

• 存在安全风险
• 应明确指定允许的域名

4. 不要将 .env 提交到 Git

• 已配置在 .gitignore 中
• 但要定期检查确保没有意外提交

故障排查

问题1：修改 .env 后没有生效

# 重启 Django 服务
# 如果是用 manage.py runserver
Ctrl+C 停止，然后重新启动

# 如果是用 gunicorn 或其他 WSGI 服务器
# 重启对应的服务

问题2：validate_config.py 报错

常见错误及解决：

# 生成新密钥并更新 .env
python -c "from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())"
# 复制输出，替换 .env 中的 DJANGO_SECRET_KEY

# 编辑 .env 文件
notepad .env
# 修改 DB_PASSWORD=your_strong_password

# 编辑 .env 文件
notepad .env
# 修改为：DJANGO_ALLOWED_HOSTS=example.com,www.example.com

问题3：无法连接到数据库

# 1. 验证配置
python validate_config.py

# 2. 检查数据库服务是否运行
# MySQL: services.msc 查看 MySQL 服务状态

# 3. 测试数据库连接
python -c "import MySQLdb; conn = MySQLdb.connect(host='127.0.0.1', user='root', passwd='your_password', db='dms_datasource'); print('连接成功'); conn.close()"

📚 相关文档

• config/env.py - 环境变量加载逻辑
• application/settings.py - Django 配置
• .env使用说明.md - 旧版说明文档（仅供参考）

💡 最佳实践总结

1. 开发环境

2. 生产环境

3. 日常维护