AFFiNE 白板文档工具部署教程

AFFiNE 是新一代的开源知识管理工具，融合了文档编辑、白板绘制和数据库管理三大核心功能。它可以被看作 Notion + Miro 的开源替代方案，支持在文档和白板模式之间自由切换。本教程将在搬瓦工 VPS 上使用 Docker 部署 AFFiNE 自托管服务。

一、AFFiNE 核心特色

文档模式：类似 Notion 的块编辑器，支持富文本、代码块、列表、表格、嵌入等多种内容块。
白板模式：无限画布上自由绘制、摆放文档块、添加形状和连接线，适合头脑风暴和流程设计。
文档-白板互通：文档内容可以直接拖入白板，白板中的块也可以作为独立文档打开。
数据库视图：支持在文档中嵌入表格数据库，提供看板和表格视图。
Markdown 支持：完整的 Markdown 语法支持，支持导入导出 Markdown 文件。
本地优先：采用 CRDT 技术实现本地优先的数据存储，离线编辑后自动同步。

二、环境准备

操作系统：Ubuntu 20.04+（推荐 Ubuntu 22.04）。
内存：至少 2GB RAM，推荐 4GB。
磁盘：至少 15GB 可用空间。
Docker：已安装 Docker 和 Docker Compose（参考 Docker 安装教程）。

购买搬瓦工 VPS 可以参考搬瓦工全部方案，使用优惠码 NODESEEK2026 可享受 6.77% 折扣。

三、Docker Compose 部署

3.1 创建项目目录

mkdir -p /opt/affine && cd /opt/affine

3.2 创建 Docker Compose 文件

cat > docker-compose.yml <<'EOF'
version: '3.8'

services:
  affine:
    image: ghcr.io/toeverything/affine-graphql:stable
    container_name: affine
    restart: always
    ports:
      - "3010:3010"
      - "5555:5555"
    environment:
      NODE_OPTIONS: "--import=./scripts/register.js"
      AFFINE_CONFIG_PATH: "/root/.affine/config"
      REDIS_SERVER_HOST: redis
      DATABASE_URL: "postgresql://affine:your_db_password@db:5432/affine"
      NODE_ENV: production
      AFFINE_ADMIN_EMAIL: "admin@example.com"
      AFFINE_ADMIN_PASSWORD: "YourAdminPass123"
      AFFINE_SERVER_HOST: "0.0.0.0"
      AFFINE_SERVER_PORT: "3010"
    volumes:
      - affine_config:/root/.affine/config
      - affine_storage:/root/.affine/storage
    depends_on:
      redis:
        condition: service_healthy
      db:
        condition: service_healthy
    command: ['sh', '-c', 'node ./scripts/self-host-predeploy && node ./dist/index.js']

  db:
    image: postgres:16-alpine
    container_name: affine-db
    restart: always
    environment:
      POSTGRES_USER: affine
      POSTGRES_PASSWORD: your_db_password
      POSTGRES_DB: affine
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U affine"]
      interval: 10s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7-alpine
    container_name: affine-redis
    restart: always
    volumes:
      - redis_data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  affine_config:
  affine_storage:
  postgres_data:
  redis_data:
EOF

请修改数据库密码和管理员凭据为安全的值。

3.3 启动 AFFiNE

docker compose up -d
docker compose logs -f affine

等待数据库迁移完成后，访问 http://你的服务器IP:3010 即可使用 AFFiNE。

四、Nginx 反向代理

apt update && apt install nginx -y

cat > /etc/nginx/sites-available/affine <<'EOF'
server {
    listen 80;
    server_name affine.example.com;

    client_max_body_size 100m;

    location / {
        proxy_pass http://127.0.0.1:3010;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}
EOF

ln -s /etc/nginx/sites-available/affine /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx

apt install certbot python3-certbot-nginx -y
certbot --nginx -d affine.example.com

五、使用 AFFiNE

5.1 文档编辑

创建新页面后进入文档模式，输入 / 调出块菜单插入各种内容块。AFFiNE 支持标准 Markdown 快捷键，例如 # 创建标题、- 创建列表、``` 创建代码块。编辑器支持拖拽调整块顺序和嵌套层级。

5.2 白板绘制

切换到白板模式后，你将看到一个无限画布。可以在画布上自由放置文本、形状、图片和文档块，使用连接线建立关系。白板适合做思维导图、流程图和项目规划。文档中的任何块都可以直接拖到白板上使用。

5.3 工作区与协作

AFFiNE 以工作区为单位组织内容。每个工作区可以包含多个页面和收藏夹。自托管版本支持邀请团队成员加入工作区，共同编辑文档和白板。通过管理面板可以管理用户和权限。

5.4 数据导入导出

AFFiNE 支持从 Markdown 文件导入内容，也可以将页面导出为 Markdown、PDF 或 HTML 格式。这使得数据迁移和备份非常方便。

六、备份与升级

# 备份数据库
docker exec affine-db pg_dump -U affine affine > /opt/affine/backup_$(date +%Y%m%d).sql

# 备份存储文件
docker cp affine:/root/.affine/storage /opt/affine/storage_backup_$(date +%Y%m%d)

# 升级 AFFiNE
cd /opt/affine
docker compose pull
docker compose down
docker compose up -d

七、常见问题

WebSocket 连接失败：确保 Nginx 配置中包含 WebSocket 相关的 Upgrade 和 Connection 头。
上传文件大小限制：在 Nginx 配置中调整 client_max_body_size 参数。
内存不足：AFFiNE 的 Node.js 进程对内存需求较高，建议 VPS 至少 2GB 内存。

总结

AFFiNE 将文档和白板完美融合，是目前最具创新性的开源知识管理工具之一。部署在搬瓦工 VPS 上可以享受完整的自托管体验。如果你更偏重纯文档协作，可以参考 Docmost 部署教程。购买搬瓦工 VPS 请参考全部方案，使用优惠码 NODESEEK2026 可享受折扣。更多教程请访问搬瓦工VPS中文网。