129 lines
3.6 KiB
Markdown
129 lines
3.6 KiB
Markdown
# 环境变量配置指南
|
||
|
||
本文档说明 Paper Burner X 项目的环境变量配置要求。
|
||
|
||
## 快速开始
|
||
|
||
### 开发环境（开箱即用）
|
||
|
||
开发环境可以使用默认值，系统会自动生成安全的开发密钥并给出警告提示：
|
||
|
||
```bash
|
||
# 无需配置即可运行（会有警告提示）
|
||
npm run dev
|
||
```
|
||
|
||
### 生产环境（必须配置）
|
||
|
||
生产环境必须设置以下关键安全变量：
|
||
|
||
```bash
|
||
# 必需的环境变量
|
||
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
|
||
|
||
```bash
|
||
# 生成 JWT_SECRET（32 字节 Base64）
|
||
openssl rand -base64 32
|
||
|
||
# 生成 ENCRYPTION_SALT（32 字节 Base64）
|
||
openssl rand -base64 32
|
||
```
|
||
|
||
### 使用 Node.js
|
||
|
||
```bash
|
||
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"
|
||
```
|
||
|
||
## 配置示例
|
||
|
||
### .env（开发环境）
|
||
|
||
```bash
|
||
NODE_ENV=development
|
||
DEPLOYMENT_MODE=frontend
|
||
# JWT_SECRET 和 ENCRYPTION_SALT 可以不设置，系统会自动生成
|
||
```
|
||
|
||
### .env（生产环境）
|
||
|
||
```bash
|
||
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`。
|
||
|