生产部署方案

> **文档版本**: v1.0.0
> **创建日期**: 2026-02-12
> **最后更新**: 2026-02-12
> **维护人**: 未来鸟FutureBird码巢企业服务引擎开发组
> **状态**: [最新]

---

# &#128640; 生产环境部署指南

## 问题说明

如果您发现生产环境没有数据和配置信息，这是因为：

1. **数据库未初始化** - 需要运行数据库迁移
2. **环境变量未配置** - 生产环境需要配置真实的数据库连接和 API 密钥
3. **种子数据未导入** - 系统配置、默认管理员账号等需要手动创建

---

## &#128295; 解决方案

### 第一步：配置环境变量

在生产环境创建 `.env.production` 文件：

```bash
# 数据库配置（⚠️ 必须修改）
DATABASE_URL=postgresql://用户名:密码@数据库地址:端口/数据库名?sslmode=require

# 应用配置（⚠️ 必须修改）
NEXT_PUBLIC_APP_URL=https://your-domain.com
NODE_ENV=production

# JWT密钥（⚠️ 必须修改为强密码）
JWT_SECRET=your-super-secret-jwt-key-at-least-32-characters-long

# 超级管理员账号（⚠️ 必须修改）
ADMIN_USERNAME=admin
ADMIN_PASSWORD=your-strong-password-at-least-12-chars
ADMIN_EMAIL=admin@yourdomain.com

# 对象存储配置（如使用 OSS，请配置）
OSS_ENDPOINT=your-oss-endpoint
OSS_ACCESS_KEY_ID=your-access-key
OSS_SECRET_KEY=your-secret-key
OSS_BUCKET=your-bucket-name

# 短信服务配置（如使用短信，请配置）
SMS_ACCESS_KEY_ID=your-sms-access-key
SMS_SECRET_KEY=your-sms-secret-key
SMS_SIGN_NAME=your-sign-name
SMS_TEMPLATE_CODE=your-template-code

# 微信集成配置（如使用微信，请配置）
WECHAT_APP_ID=your-wechat-app-id
WECHAT_APP_SECRET=your-wechat-app-secret
```

### 第二步：运行数据库迁移

```bash
# 方式1：使用 Drizzle（推荐）
pnpm drizzle-kit push

# 方式2：手动执行 SQL
psql $DATABASE_URL -f drizzle/migrations/0001_init.sql
```

### 第三步：初始化种子数据

创建一个种子数据脚本 `scripts/seed-data.ts`：

```typescript
import { getDb } from '@/db';

async function seedData() {
  const db = await getDb();

// 1. 创建默认管理员账号
  const adminPassword = process.env.ADMIN_PASSWORD || 'admin123';
  const hashedPassword = await hashPassword(adminPassword);

await db.execute(`
    INSERT INTO users (username, email, password, role, status)
    VALUES (
      '${process.env.ADMIN_USERNAME}',
      '${process.env.ADMIN_EMAIL}',
      '${hashedPassword}',
      'admin',
      'active'
    )
    ON CONFLICT (username) DO NOTHING;
  `);

console.log('✓ 创建默认管理员账号');

// 2. 创建系统配置
  const defaultConfigs = [
    { key: 'system.name', value: '企业管理数字化中台' },
    { key: 'system.version', value: '1.0.0' },
    { key: 'system.timezone', value: 'Asia/Shanghai' },
  ];

for (const config of defaultConfigs) {
    await db.execute(`
      INSERT INTO system_settings (config_key, config_value)
      VALUES ('${config.key}', '${config.value}')
      ON CONFLICT (config_key) DO UPDATE
      SET config_value = '${config.value}';
    `);
  }

console.log('✓ 创建系统配置');

console.log('\n✅ 数据初始化完成');
}

seedData().catch(console.error);
```

运行种子脚本：

```bash
npx tsx scripts/seed-data.ts
```

### 第四步：启动服务

```bash
pnpm build
pnpm start
```

---

## &#128203; 部署检查清单

- [ ] 创建 `.env.production` 文件
- [ ] 配置数据库连接信息
- [ ] 配置 JWT_SECRET（必须）
- [ ] 配置超级管理员账号和密码
- [ ] 配置应用域名 NEXT_PUBLIC_APP_URL
- [ ] 运行数据库迁移
- [ ] 运行种子数据初始化
- [ ] 测试登录功能
- [ ] 验证系统配置是否加载

---

## ⚠️ 常见问题

### 1. 数据库连接失败

**错误**: `connection refused` 或 `password authentication failed`

**解决**:
- 检查 `DATABASE_URL` 是否正确
- 确认数据库地址、端口、用户名、密码
- 检查数据库是否允许远程连接
- 检查防火墙设置

### 2. 表不存在

**错误**: `relation "xxx" does not exist`

**解决**:
- 运行数据库迁移：`pnpm drizzle-kit push`
- 或手动执行 SQL 文件：`psql $DATABASE_URL -f drizzle/migrations/0001_init.sql`

### 3. 无法登录

**原因**: 超级管理员账号未创建或密码错误

**解决**:
- 检查 `ADMIN_USERNAME` 和 `ADMIN_PASSWORD` 环境变量
- 运行种子数据脚本创建管理员账号
- 如果忘记密码，直接修改数据库：

```sql
UPDATE users
SET password = '新密码的哈希值'
WHERE username = 'admin';
```

### 4. 系统配置缺失

**原因**: 未运行种子数据脚本

**解决**:
- 运行种子数据脚本
- 或手动在管理后台添加配置

---

## &#128274; 安全建议

1. **不要使用默认密码**
   - 修改 `ADMIN_PASSWORD` 为强密码
   - 定期更换管理员密码

2. **保护环境变量**
   - 不要将 `.env.production` 提交到版本控制
   - 使用密钥管理服务（如 AWS Secrets Manager）
   - 限制文件访问权限：`chmod 600 .env.production`

3. **数据库安全**
   - 使用强密码
   - 启用 SSL 连接（`sslmode=require`）
   - 限制数据库访问 IP
   - 定期备份数据

4. **JWT 安全**
   - 使用长且随机的 JWT_SECRET
   - 定期更换 JWT_SECRET（需要重新登录）
   - 设置合理的过期时间

---

## &#128222; 获取帮助

如果以上步骤仍然无法解决问题，请提供以下信息：

1. 错误信息（完整日志）
2. `.env.production` 配置（脱敏后）
3. 数据库版本
4. Node.js 版本
5. 部署方式（Docker、VPS、云服务等）