koa3-demo/docs/environment-setup.md

环境变量配置指南

概述

koa3-demo 项目现在包含完整的环境变量验证系统，确保应用启动前所有必需的环境变量都已正确配置。

安全改进

根据中小型项目安全规范要求，我们已经实现：

• ✅ 移除了 JWT_SECRET 的默认值，强制要求环境变量配置
• ✅ 增强了环境变量验证，包括格式和安全性检查
• ✅ 提供了完整的 .env.example 模板文件
• ✅ 添加了敏感信息脱敏显示功能

快速开始

1. 复制环境变量模板

cp .env.example .env

2. 配置必需的环境变量

编辑 .env 文件，设置以下必需变量：

# 会话密钥（用于 cookie 签名）
SESSION_SECRET=your-super-secret-session-key-at-least-32-chars,backup-secret-key

# JWT 密钥（用于令牌签名和验证）
JWT_SECRET=your-super-secret-jwt-key-must-be-at-least-32-characters-long

3. 启动应用

# 开发环境
bun run dev

# 生产环境
bun run start

环境变量详解

必需变量 (Required)

变量名	描述	要求
SESSION_SECRET	会话密钥，用于 cookie 签名	支持多个密钥（逗号分隔），用于密钥轮换
JWT_SECRET	JWT 令牌密钥	最少 32 个字符，用于令牌签名和验证

可选变量 (Optional)

变量名	默认值	描述
NODE_ENV	development	运行环境 (development/production/test)
PORT	3000	服务器端口
LOG_DIR	logs	日志文件目录
HTTPS_ENABLE	off	是否启用 HTTPS (on/off)

验证功能

应用启动时会自动验证：

1. 必需变量检查：确保所有必需的环境变量都已设置
2. 格式验证：检查变量格式是否正确（如端口号是数字）
3. 安全性检查：验证密钥长度和复杂度
4. 脱敏显示：启动日志中安全地显示环境变量状态

测试环境变量配置

# 运行环境变量验证测试
bun run test:env

生产环境最佳实践

1. 密钥生成：使用安全的随机字符串生成器
2. 密钥轮换：定期更换密钥，SESSION_SECRET 支持多密钥轮换
3. 环境隔离：不同环境使用不同的密钥
4. 版本控制：永远不要将 .env 文件提交到 Git

Docker 部署

使用环境变量文件

# 复制并编辑环境变量
cp .env.example .env.docker

# 使用 docker-compose
docker-compose --env-file .env.docker up

直接设置环境变量

export SESSION_SECRET="your-production-session-secret"
export JWT_SECRET="your-production-jwt-secret"
docker-compose up

故障排除

应用启动失败

如果应用启动时出现环境变量相关错误：

1. 检查 .env 文件是否存在
2. 确认所有必需的环境变量都已设置
3. 验证 JWT_SECRET 长度至少 32 个字符
4. 确保 SESSION_SECRET 不为空

查看详细错误信息

应用会在启动时显示详细的验证信息：

[INFO] 🔍 开始验证环境变量...
[ERROR] ❌ 缺少必需的环境变量:
[ERROR]    - JWT_SECRET
[ERROR] 请设置这些环境变量后重新启动应用

安全注意事项

1. 密钥强度：使用至少 32 个字符的强随机密钥
2. 定期轮换：定期更换密钥，特别是在生产环境
3. 访问控制：限制对环境变量文件的访问权限
4. 监控：监控环境变量的访问和使用情况

相关文件

• .env.example - 环境变量模板文件
• src/utils/envValidator.js - 环境变量验证模块
• src/global.js - 应用初始化和环境变量集成
• docker-compose.yml - Docker 环境配置