AFFiNE：开源Notion+Miro融合知识库部署与使用指南

📋 官方信息

项目名称	AFFiNE
仓库地址	https://github.com/toeverything/AFFiNE
官方网站	https://affine.pro
最新更新	2026年10月
项目定位	开源的下一代知识库，融合文档、白板和项目管理

🎯 项目背景

AFFiNE 由 toeverything 团队开发，定位是"开源的 Notion + Miro 替代品"。传统笔记工具要么偏文档（Notion），要么偏白板（Miro、FigJam），而 AFFiNE 把两者融合在同一个画布中：你可以在同一个页面里既有结构化的文档块，又有自由拖拽的白板元素，实现"所见即所得"的无限画布工作区。

项目名称 AFFiNE 来自拉丁文"affine"（关联），代表知识之间的连接。它基于 Next.js 和 Yjs 协作编辑框架构建，支持实时多人协作。自 2022 年开源以来，已获得超过 3 万 Star，是目前最活跃的开源知识库项目之一。最新版本还集成了 AI Copilot 功能，可以帮你写文档、总结内容。

✨ 核心特性

混合画布：文档模式 + 白板模式无缝切换，同一页面内自由排版
块级编辑：类似 Notion 的 Block 系统，支持文本、列表、表格、代码、嵌入等 40+ 种块
实时协作：基于 Yjs CRDT，多人同时编辑无冲突
AI Copilot：内置 AI 助手，支持文本润色、摘要、翻译、续写
公开分享：一键将页面发布为公开网页
版本历史：自动保存编辑历史，可回溯任意版本
多工作区：支持创建多个 Workspace，隔离不同项目
私有化部署：完整自托管，数据完全可控

💻 环境要求

Docker 部署：Docker 20.10+，Docker Compose v2+，内存 4GB 以上（推荐 8GB）
磁盘空间：至少 5GB 可用空间
网络：需要能拉取 Docker 镜像
浏览器：Chrome / Edge / Firefox 最新版

🚀 详细部署步骤

方式一：Docker Compose 部署（官方推荐）

# 1. 创建工作目录
mkdir affine && cd affine

# 2. 下载官方 docker-compose.yml
curl -L -o docker-compose.yml \
  https://github.com/toeverything/AFFiNE/releases/latest/download/docker-compose.yml

# 3. 创建配置目录
mkdir -p config

# 4. 创建配置文件 config/config.json
cat > config/config.json << 'EOF'
{
  "enableTelemetry": false,
  "auth": {
    "redirectUri": "http://localhost:3000"
  }
}
EOF

# 5. 启动所有服务
docker compose up -d

方式二：Docker 单容器快速体验

docker run -d \
  --name affine \
  -v ./affine-data:/app/data \
  -p 3000:3000 \
  ghcr.io/toeverything/affine-self-hosted:latest

注意：单容器模式适合个人快速体验，生产环境建议使用 Docker Compose 完整版（包含独立的 PostgreSQL 和 Redis）。

📝 完整 docker-compose.yml 说明

name: affine
services:
  affine:
    image: ghcr.io/toeverything/affine:stable
    container_name: affine_server
    ports:
      - '3000:3000'
    depends_on:
      redis:
        condition: service_healthy
      postgres:
        condition: service_healthy
    volumes:
      - ./data:/app/data
    environment:
      - DATABASE_URL=postgresql://affine:affine@postgres:5432/affine
      - REDIS_URL=redis://redis:6379
    restart: unless-stopped

  postgres:
    image: postgres:16
    container_name: affine_postgres
    environment:
      - POSTGRES_USER=affine
      - POSTGRES_PASSWORD=affine
      - POSTGRES_DB=affine
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U affine"]
      interval: 5s
      timeout: 5s
      retries: 10
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    container_name: affine_redis
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 5s
      retries: 10
    restart: unless-stopped

volumes:
  pgdata:

🔧 AI Copilot 配置（可选）

在 config/config.json 中添加：

{
  "copilot": {
    "byok": {
      "enabled": true
    }
  }
}

启用后，工作区管理员可以在设置 → 集成 → AI BYOK 中配置自己的 OpenAI API Key。

✅ 启动验证

等待所有容器启动完成（首次约 2-3 分钟）
访问 http://服务器IP:3000
首次注册的账号即为管理员
创建一个新页面，尝试输入文字和拖拽白板元素
确认文档编辑和白板功能正常

⚠️ 常见坑

首次启动需要运行数据库迁移，看到"migrations"日志是正常的
如果 502 错误，等待 1-2 分钟让服务完全启动
反向代理时必须配置 WebSocket 支持（AFFiNE 使用 WebSocket 做实时协作）
数据持久化目录是 ./data 和 Docker volume pgdata，备份时不要遗漏

📖 使用方法

创建页面

登录后自动进入默认 Workspace，点击"New Page"创建新页面。默认是文档模式，点击左上角可以切换到白板模式。

混合编辑

在文档模式中输入 / 可以插入各种块（标题、列表、表格、图片、代码块等）。在白板模式中可以自由拖拽元素、绘制图形、添加便签。

分享页面

点击页面右上角的"Share"按钮，可以生成公开链接，任何人都可以通过链接查看你的页面。

❓ 常见问题

Q1: 免费版和付费版有什么区别？
A: 自托管开源版功能完整，只是没有官方云服务的多团队管理和企业级支持。个人和小团队使用完全足够。

Q2: 支持导入 Notion 数据吗？
A: 支持。可以从 Notion 导出 Markdown 后导入 AFFiNE。

Q3: 数据存储在哪里？
A: 数据库在 PostgreSQL 容器中，文件存储在 ./data 目录。所有数据都在你的服务器上。

Q4: 如何配置域名和 HTTPS？
A: 使用 Nginx 反向代理，确保转发 WebSocket 请求。在 config.json 中设置 auth.redirectUri 为你的域名。

Q5: 如何更新？
A: docker compose pull && docker compose up -d。官方会自动处理数据库迁移。

🔗 跳转链接

GitHub 仓库：https://github.com/toeverything/AFFiNE
官方网站：https://affine.pro
官方文档：https://docs.affine.pro
在线体验：https://app.affine.pro