零停机升级指南：Docmost数据库迁移与版本更新全流程

你是否曾因系统升级导致服务中断而收到用户投诉？是否在数据迁移过程中担心过数据丢失风险？本文将带你掌握Docmost的无缝升级技术，通过Kysely迁移工具与PostgreSQL数据库的完美配合，实现零停机数据迁移与版本升级。

迁移系统架构解析

Docmost采用Kysely作为类型安全的SQL查询构建器，结合自定义迁移系统实现数据库版本管理。核心架构包含三个层级：

graph TD
    A[应用层] -->|调用| B[数据访问层]
    B --> C(Kysely查询构建器)
    C --> D[PostgreSQL数据库]
    E[迁移管理层] -->|执行| F[迁移脚本]
    F --> D

数据库模块配置位于apps/server/src/database/database.module.ts，通过NestJS的依赖注入系统提供数据库连接和仓储服务。系统启动时会自动建立数据库连接并尝试连接15次（每次间隔3秒），确保在数据库暂时不可用时仍能恢复连接。

迁移脚本管理规范

所有迁移脚本集中存放在apps/server/src/database/migrations目录，采用时间戳+描述的命名规范：

20240324T085400-uuid_v7_fn.ts      // UUID生成函数
20240324T085500-workspaces.ts      // 工作区表结构
20240324T085600-users.ts           // 用户表结构
20250715T070817-mfa.ts             // 多因素认证功能

最新的迁移脚本20250901T184612-attachments-search.ts实现了附件搜索功能，展示了如何通过迁移添加全文搜索能力。

实战迁移操作指南

前置准备工作

1. 备份数据库（生产环境必备）：

pg_dump -U username -d docmost > backup_before_migration.sql

2. 检查当前迁移状态：

cd apps/server
npm run migration:latest

核心迁移命令

命令	作用	风险级别
migration:up	执行单个迁移	低
migration:down	回滚单个迁移	中
migration:latest	执行所有未应用迁移	中
migration:redo	回滚并重新执行最后一个迁移	高
migration:reset	回滚所有迁移	极高

⚠️ 警告：生产环境禁止使用migration:reset和migration:redo命令，可能导致数据丢失

版本升级全流程

以从v0.22.0升级到v0.23.2为例，完整升级流程如下：

# 1. 拉取最新代码
git pull origin main

# 2. 安装依赖
pnpm install

# 3. 构建应用
pnpm run build:server

# 4. 执行数据库迁移
cd apps/server
npm run migration:latest

# 5. 重启服务
pm2 restart docmost-server

迁移工具会自动记录已应用的迁移版本，确保每个脚本只执行一次。迁移过程中，系统通过事务保证每个迁移的原子性，要么全部成功，要么全部失败回滚。

高级迁移场景处理

数据量大表结构变更

对于包含百万级记录的表结构变更，推荐使用PostgreSQL的CONCURRENTLY选项创建索引，避免长时间表锁定：

// 安全创建索引示例
export async function up(db: Kysely<any>): Promise<void> {
  await db.schema
    .alterTable('pages')
    .addColumn('contributor_ids', 'jsonb[]')
    .execute();
    
  // 并发创建索引，不阻塞读写
  await db.raw`
    CREATE INDEX CONCURRENTLY idx_pages_contributor_ids 
    ON pages USING GIN (contributor_ids)
  `;
}

相关实现可参考20250327T145832-add-contributorIds-to-pages.ts迁移脚本。

多环境迁移策略

开发环境：启用自动迁移，每次启动应用时执行未应用的迁移 生产环境：手动控制迁移时机，通过CI/CD管道执行迁移命令

环境配置通过NODE_ENV环境变量控制，相关逻辑在数据库模块的onApplicationBootstrap方法中实现：

if (this.environmentService.getNodeEnv() === 'production') {
  await this.migrationService.migrateToLatest();
}

迁移监控与问题排查

迁移过程中遇到问题时，可通过以下方式诊断：

1. 查看应用日志：迁移失败会记录详细错误信息
2. 检查迁移记录表：

SELECT * FROM kysely_migrations ORDER BY executed_at DESC;

3. 验证数据库连接：使用迁移工具测试连接

tsx src/database/migrate.ts test-connection

常见问题解决方案：

• 迁移冲突：手动编辑迁移脚本解决冲突后重新执行
• 数据格式错误：编写数据转换脚本处理历史数据
• 连接超时：检查DATABASE_URL配置和PostgreSQL服务状态

版本升级最佳实践

1. 灰度发布策略：

   • 先升级只读副本
   • 切换流量验证
   • 最后升级主库

2. 回滚预案：

   • 升级前备份关键表
   • 准备对应版本的降级迁移脚本
   • 测试环境验证回滚流程

3. 性能优化：

   • 迁移窗口选择低峰期
   • 大表变更拆分多个小批次
   • 禁用非必要索引再重建

通过本文介绍的迁移技术，你已经掌握了Docmost的数据库版本管理系统。无论是日常小版本升级还是跨版本的重大架构变更，这套迁移体系都能确保数据安全和服务连续性。记得定期查看apps/server/src/database/migrations目录下的最新迁移脚本，了解Docmost的数据模型演进路线。

下一篇：《Docmost高可用部署方案：主从复制与自动故障转移》，将介绍如何构建99.99%可用性的Docmost服务架构。