paper-burner/server/ENV_CONFIG.md

环境变量配置指南

本文档说明 Paper Burner X 项目的环境变量配置要求。

快速开始

开发环境（开箱即用）

开发环境可以使用默认值，系统会自动生成安全的开发密钥并给出警告提示：

# 无需配置即可运行（会有警告提示）
npm run dev

生产环境（必须配置）

生产环境必须设置以下关键安全变量：

# 必需的环境变量
NODE_ENV=production
JWT_SECRET=<生成强随机字符串>
ENCRYPTION_SALT=<生成强随机字符串>
CORS_ORIGIN=https://yourdomain.com,https://www.yourdomain.com

# 推荐配置
FILE_VALIDATION_STRICT=true
DATABASE_URL=postgresql://...

环境变量说明

🔴 必需配置（生产环境）

变量名	说明	示例	开发环境	生产环境
NODE_ENV	环境模式	production	可选	必需
JWT_SECRET	JWT 签名密钥	随机字符串	自动生成	必需
ENCRYPTION_SALT	加密 salt	随机字符串	使用默认值	必需

🟡 部署配置

变量名	说明	示例	默认值
DEPLOYMENT_MODE	部署模式	frontend / backend	frontend
CORS_ORIGIN	CORS 允许的源	https://example.com	开发环境允许所有源
PORT	服务器端口	3000	3000

🟢 安全配置

变量名	说明	示例	默认值
DISABLE_CSP	是否禁用 CSP	true / false	false
CSP_ALLOW_INLINE	是否允许内联脚本	true / false	前端模式自动启用
FILE_VALIDATION_STRICT	文件类型验证严格模式	true / false	false
ALLOWED_MIME_TYPES	允许的文件类型	application/pdf,text/markdown	内置白名单
MAX_UPLOAD_SIZE	最大文件大小（MB）	100	100

🔵 数据库配置

变量名	说明	示例
DATABASE_URL	Prisma 数据库连接 URL	postgresql://user:pass@localhost:5432/db

🟣 JWT 配置

变量名	说明	示例	默认值
JWT_EXPIRES_IN	JWT 过期时间	7d	7d

生成安全密钥

使用 OpenSSL

# 生成 JWT_SECRET（32 字节 Base64）
openssl rand -base64 32

# 生成 ENCRYPTION_SALT（32 字节 Base64）
openssl rand -base64 32

使用 Node.js

node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

配置示例

.env（开发环境）

NODE_ENV=development
DEPLOYMENT_MODE=frontend
# JWT_SECRET 和 ENCRYPTION_SALT 可以不设置，系统会自动生成

.env（生产环境）

NODE_ENV=production
JWT_SECRET=<生成的强随机字符串>
ENCRYPTION_SALT=<生成的强随机字符串>
CORS_ORIGIN=https://yourdomain.com,https://www.yourdomain.com
FILE_VALIDATION_STRICT=true
DATABASE_URL=postgresql://user:password@localhost:5432/paperburner

安全提示

1. 永远不要将 .env 文件提交到 Git
2. 生产环境必须设置所有安全相关变量
3. 定期轮换密钥（会影响现有用户登录，需要配合迁移策略）
4. 使用强随机字符串作为密钥（至少 32 字节）
5. 限制 CORS_ORIGIN 为实际需要的域名

迁移注意事项

⚠️ 重要：更改 ENCRYPTION_SALT 会导致已加密的数据无法解密。如需更改 salt，需要：

1. 先解密所有数据
2. 更改 salt
3. 重新加密数据

因此，建议在生产环境部署前就设置好 ENCRYPTION_SALT。