Wiki.js升级指南：版本升级与迁移注意事项

概述

Wiki.js作为一款现代化的开源Wiki平台，其版本迭代频繁且功能不断增强。本文将为您提供全面的Wiki.js升级指南，涵盖从版本2.x到最新版本的升级策略、数据迁移注意事项以及常见问题解决方案。

升级前准备工作

1. 数据备份策略

在进行任何升级操作前，必须确保数据安全。Wiki.js的数据备份应包括：

-- 数据库备份（以PostgreSQL为例）
pg_dump -U wikijs -h localhost wiki > wiki_backup_$(date +%Y%m%d).sql

-- 文件备份
tar -czf wiki_files_backup_$(date +%Y%m%d).tar.gz /path/to/wiki/data/

2. 版本兼容性检查

使用以下命令检查当前版本和依赖状态：

# 查看当前版本
node -v
npm -v

# 检查Wiki.js版本
cat package.json | grep '"version"'

# 检查数据库版本
psql --version

3. 环境要求验证

确保目标环境满足新版本要求：

组件	最低要求	推荐版本
Node.js	14.x	16.x或18.x
PostgreSQL	9.5	13.x或更高
Nginx	1.14	1.20+
内存	1GB	2GB+

升级流程详解

1. 标准升级流程

flowchart TD
    A[开始升级] --> B[完整数据备份]
    B --> C[停止Wiki.js服务]
    C --> D[备份配置文件]
    D --> E[更新代码库]
    E --> F[安装依赖]
    F --> G[运行数据库迁移]
    G --> H[启动服务测试]
    H --> I[验证功能]
    I --> J[升级完成]

2. 具体操作步骤

步骤1：停止服务

# 使用PM2
pm2 stop wiki

# 或直接停止进程
pkill -f "node server"

步骤2：代码更新

# Git方式更新
git fetch --all
git checkout tags/2.5.0  # 替换为目标版本

# 或下载发布包
wget https://github.com/Requarks/wiki/releases/download/2.5.0/wiki-2.5.0.tar.gz
tar -xzf wiki-2.5.0.tar.gz

步骤3：依赖安装

# 清理旧依赖
rm -rf node_modules package-lock.json

# 安装新依赖
npm install --production

# 或使用Yarn
yarn install --production

步骤4：数据库迁移

# 自动运行迁移脚本
npm run migrate

# 或手动检查迁移状态
node -e "require('./server/db/migrator-source.js').migrate()"

数据库迁移注意事项

1. 迁移脚本执行顺序

Wiki.js使用Knex.js进行数据库迁移，迁移文件按版本号顺序执行：

// 迁移文件示例：server/db/migrations/2.5.128.js
exports.up = async knex => {
  await knex('users').update({
    email: knex.raw('LOWER(??)', ['email'])
  })
}

exports.down = knex => { }

2. 常见迁移问题

问题1：索引冲突

-- 解决方案：先删除旧索引
DROP INDEX IF EXISTS idx_users_email;
CREATE UNIQUE INDEX idx_users_email ON users(LOWER(email));

问题2：数据类型变更

-- 文本长度扩展
ALTER TABLE pages ALTER COLUMN content TYPE TEXT;

配置文件升级

1. config.yml配置更新

新旧版本配置对比：

# 旧版本配置
db:
  type: postgres
  host: localhost
  port: 5432

# 新版本配置
db:
  type: postgres
  host: localhost
  port: 5432
  ssl: false
  sslOptions:
    auto: true

2. 环境变量配置

推荐使用环境变量进行配置：

# .env文件配置
DB_TYPE=postgres
DB_HOST=localhost
DB_PORT=5432
DB_USER=wikijs
DB_PASS=wikijsrocks
DB_NAME=wiki

Docker容器升级

1. Docker Compose升级

version: "3.8"
services:
  wiki:
    image: requarks/wiki:2.5
    environment:
      DB_TYPE: postgres
      DB_HOST: db
      DB_PORT: 5432
      DB_USER: wikijs
      DB_PASS: wikijsrocks
      DB_NAME: wiki
    depends_on:
      - db
    ports:
      - "3000:3000"
    volumes:
      - wiki-data:/wiki/data

  db:
    image: postgres:13-alpine
    environment:
      POSTGRES_DB: wiki
      POSTGRES_USER: wikijs
      POSTGRES_PASSWORD: wikijsrocks
    volumes:
      - db-data:/var/lib/postgresql/data

volumes:
  wiki-data:
  db-data:

2. 容器数据迁移

# 备份容器数据
docker exec wiki-container tar -czf /tmp/wiki-backup.tar.gz /wiki/data

# 新容器数据恢复
docker run --rm -v wiki-data:/data alpine tar -xzf /backup/wiki-backup.tar.gz -C /data

故障排除与回滚

1. 常见升级问题

问题：依赖冲突

# 解决方案：清理缓存
npm cache clean --force
rm -rf node_modules package-lock.json
npm install

问题：数据库连接失败

// 检查连接配置
const knex = require('knex')({
  client: 'pg',
  connection: {
    host: process.env.DB_HOST,
    user: process.env.DB_USER,
    password: process.env.DB_PASS,
    database: process.env.DB_NAME
  }
});

2. 紧急回滚方案

# 步骤1：停止新版本服务
pm2 stop wiki-new

# 步骤2：恢复备份数据
psql -U wikijs -h localhost wiki < wiki_backup.sql

# 步骤3：恢复旧版本代码
git checkout 2.4.0  # 回退到旧版本

# 步骤4：启动旧服务
pm2 start wiki-old

性能优化建议

1. 数据库优化

-- 创建性能优化索引
CREATE INDEX CONCURRENTLY idx_pages_path ON pages(path);
CREATE INDEX CONCURRENTLY idx_pages_updated_at ON pages(updated_at);

2. 缓存配置

# config.yml缓存配置
cache:
  enabled: true
  type: redis
  host: localhost
  port: 6379

监控与日志

1. 健康检查配置

// 健康检查端点
app.get('/health', (req, res) => {
  res.json({
    status: 'OK',
    timestamp: new Date().toISOString(),
    version: require('./package.json').version
  });
});

2. 日志监控

# 实时日志监控
tail -f /var/log/wiki/error.log

# 日志轮转配置
logrotate -f /etc/logrotate.d/wiki

总结

Wiki.js的升级过程需要谨慎操作，但遵循正确的流程可以确保平稳过渡。关键要点包括：

1. 始终备份数据 - 升级前必须完成完整备份
2. 测试环境验证 - 先在测试环境验证升级流程
3. 版本渐进升级 - 避免跨多个主要版本升级
4. 监控升级过程 - 实时监控日志和性能指标
5. 准备回滚方案 - 确保在出现问题时能快速恢复

通过遵循本指南，您可以安全高效地完成Wiki.js的版本升级，享受新版本带来的功能改进和性能提升。

注意：本文基于Wiki.js 2.5版本编写，具体操作请以官方文档为准。