AFFiNE：开源知识管理平台完全指南：Notion+Miro替代方案的完整教程

AFFiNE：开源知识管理平台完全指南：Notion+Miro替代方案的完整教程

背景

在知识管理和团队协作领域，Notion 以其灵活的块编辑器和数据库功能成为了文档笔记的事实标准，Miro 则以其强大的白板功能支撑了无数团队的头脑风暴和可视化协作。然而，这两款工具都存在共同的问题：数据依赖云端服务、隐私不可控、企业版定价高昂。

对于追求数据自主和成本控制的团队而言，急需一款能够融合文档编辑与白板协作于一体的开源替代方案。AFFiNE 正是为解决这一需求而诞生的新一代知识管理平台，它将笔记、白板、数据库三大核心功能完美融合，同时支持完全私有化部署，让数据完全掌控在用户手中。

本文将提供一份保姆级教学，从零开始详细讲解 AFFiNE 的部署、配置与使用，帮助个人开发者和技术团队快速搭建私有化的知识管理平台。

一、项目概述与核心特性

1.1 AFFiNE 简介

AFFiNE（发音近似"a-fine"）是由 ToEverything 团队打造的开源知识管理平台，GitHub Star 数已超过 25K。作为 Notion 和 Miro 的开源替代方案，AFFiNE 提供了一个多合一的工作空间，集成了文档编辑、白板协作、任务管理、知识库等功能。

AFFiNE 的核心设计理念是"Local-First"——本地优先。这意味着用户的数据默认存储在本地设备上，而非云端。这种设计不仅保障了数据隐私，还能在离线环境下正常工作，只需要在有网络时同步即可。

AFFiNE 特别适合以下场景：

• 追求数据隐私和自主可控的个人用户和团队
• 希望摆脱 SaaS 服务依赖，搭建私有化知识库的企业
• 需要同时使用文档编辑和白板协作的创意团队
• 寻求 Notion + Miro 组合替代方案的组织和个人开发者

1.2 核心功能模块

1.2.1 文档编辑（Docs）

AFFiNE 的文档编辑功能与 Notion 类似，采用块编辑器架构。每个文档由多个块（Block）组成，每个块可以是段落、标题、列表、代码块、图片等各种元素。

文档编辑的主要特性包括：

• 富文本编辑：支持标题、列表、引用、代码块、分割线等丰富格式
• 块操作：通过拖拽调整块的位置，通过拖放手柄复制或移动块
• 内联编辑：直接在文档中嵌入图片、视频、网页预览
• 双向链接：通过 Link Page 功能建立文档之间的关联
• 模板支持：可以创建和使用文档模板，提高效率

1.2.2 白板协作（Canvas）

AFFiNE 的白板模式借鉴了 Miro 的设计，提供无限画布（Infinite Canvas）体验。用户可以在画布上自由放置各种内容元素：

• 便签（Sticky Notes）：创建不同颜色和大小的便签
• 文本框：自由放置文本
• 图形：矩形、圆形、箭头等基础图形
• 图片：从本地上传或从网络插入
• 嵌入内容：嵌入网页、文档、表格等

更强大的是，AFFiNE 允许在同一画布上同时使用文档和便签，实现文档与白板的完美融合。

1.2.3 数据库（Database）

AFFiNE 的数据库功能借鉴了 Notion Database 的设计，提供多种视图展示数据：

表格视图（Table）：以电子表格的形式展示数据，每行是一条记录，每列是自定义属性。

看板视图（Kanban）：以看板形式展示数据，根据选定的属性（如状态、优先级）自动分组。

画廊视图（Gallery）：以卡片画廊形式展示，每张卡片显示记录的主要信息。

日历视图（Calendar）：以日历形式展示数据，适合时间相关的任务管理。

数据库支持丰富的属性类型，包括：文本、数字、单选、多选、日期、复选框、URL、邮箱、关系等。

1.2.4 视图联动与切换

AFFiNE 的一大特色是支持在文档中直接嵌入数据库视图，并提供视图联动功能：

• 嵌入的视图会实时显示数据库的最新数据
• 点击视图中的条目可以跳转到对应的详细页面
• 同一数据库可以在不同页面以不同视图展示
• 支持创建 Linked View，将多个数据库关联展示

1.3 技术特色

1.3.1 CRDT 实时协作

AFFiNE 采用 CRDT（Conflict-free Replicated Data Types）技术实现实时协作。这意味着多个用户可以同时编辑同一个文档，系统会自动合并冲突，无需担心数据丢失。

1.3.2 本地优先存储

AFFiNE 默认将数据存储在本地，通过 IndexedDB 实现。即使在离线状态下，用户依然可以正常编辑文档，网络恢复后自动同步。

1.3.3 PWA 支持

AFFiNE 支持渐进式 Web 应用（PWA），可以像原生应用一样安装到桌面，支持离线使用，并提供更好的性能体验。

1.3.4 AI 集成

AFFiNE 集成了 AI 功能，可以帮助用户进行写作辅助、内容总结、翻译等操作。在自托管版本中，可以配置自己的 AI 服务。

二、Docker Compose 部署教程

2.1 环境准备

在开始部署之前，需要确保服务器满足以下条件：

• 操作系统：Ubuntu 20.04+ / CentOS 7+ / Debian 11+
• Docker 版本：20.10+
• Docker Compose 版本：2.0+
• 内存：最低 2GB，推荐 4GB+
• 磁盘：至少 10GB 可用空间

首先检查 Docker 环境：

docker --version
docker-compose --version

如果未安装，执行以下命令安装：

# 安装 Docker
curl -fsSL https://get.docker.com | sh

# 安装 Docker Compose
apt-get update
apt-get install -y docker-compose

# 启动 Docker 并设置开机自启
systemctl start docker
systemctl enable docker

2.2 创建部署目录

在服务器上创建 AFFiNE 的部署目录，所有配置和数据将存放在此目录下：

# 创建部署目录
mkdir -p /opt/affine
cd /opt/affine

# 创建数据目录
mkdir -p ./postgres ./storage ./config

2.3 下载 Docker Compose 配置

从 AFFiNE 官方 GitHub 仓库下载最新的 Docker Compose 配置文件：

# 下载 docker-compose.yml
wget -O docker-compose.yml https://github.com/toeverything/affine/releases/latest/download/docker-compose.yml

如果下载速度较慢，可以使用 GitHub 代理加速：

wget -O docker-compose.yml https://ghproxy.com/https://github.com/toeverything/affine/releases/latest/download/docker-compose.yml

2.4 配置环境变量

下载默认的环境变量模板：

# 下载 .env 模板文件
wget -O .env https://github.com/toeverything/affine/releases/latest/download/default.env.example

编辑 .env 文件，配置数据库和存储路径：

nano .env

主要配置项说明：

# 数据库文件存放路径
DB_DATA_LOCATION=./postgres

# 上传文件存放路径
UPLOAD_LOCATION=./storage

# 配置文件存放路径
CONFIG_LOCATION=./config

# PostgreSQL 数据库用户名
DB_USERNAME=affine

# PostgreSQL 数据库密码（请修改为强密码）
DB_PASSWORD=YourStrongPassword123

# 数据库名称
DB_DATABASE=affine

# AFFiNE 服务端口（默认 3010）
APP_PORT=3010

2.5 启动服务

配置完成后，使用 Docker Compose 启动 AFFiNE：

# 拉取镜像并启动服务
docker compose up -d

# 查看服务状态
docker compose ps

# 查看服务日志
docker compose logs -f

服务启动后，通常需要等待 1-2 分钟让数据库初始化完成。可以通过以下命令检查服务健康状态：

# 检查 AFFiNE 是否就绪
curl http://localhost:3010

# 查看容器健康状态
docker compose ps

2.6 访问 AFFiNE

服务启动成功后，通过浏览器访问 http://your-server-ip:3010。首次访问时，系统会引导你创建管理员账户：

1. 输入邮箱地址
2. 设置密码
3. 输入用户名
4. 完成注册

注册完成后，系统会自动登录并进入主界面。

2.7 反向代理配置（可选）

如果需要通过域名访问并启用 HTTPS，推荐使用 Nginx 作为反向代理。

首先安装 Nginx：

apt-get update
apt-get install -y nginx

创建 Nginx 配置文件：

nano /etc/nginx/sites-available/affine

配置文件内容：

server {
    listen 80;
    server_name affine.your-domain.com;

    location / {
        proxy_pass http://localhost:3010;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        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_cache_bypass $http_upgrade;
    }
}

启用配置并申请 SSL 证书：

ln -s /etc/nginx/sites-available/affine /etc/nginx/sites-enabled/
nginx -t
certbot --nginx -d affine.your-domain.com

三、快速入门与基础使用

3.1 界面布局

AFFiNE 的主界面由以下部分组成：

左侧边栏：包含工作区导航、功能入口、用户设置等。

中间区域：主要工作区，显示当前选择的文档或白板。

右侧面板（可选）：文档属性、块设置等辅助面板。

3.2 创建第一个工作区

首次登录后，系统会引导创建工作区。工作区是 AFFiNE 中的顶级组织单元，用于隔离不同团队或个人的数据：

1. 点击"Create Workspace"
2. 输入工作区名称（如"个人笔记"或"团队知识库"）
3. 选择工作区图标和颜色
4. 完成创建

3.3 文档基础操作

3.3.1 创建文档

在左侧边栏中，点击"+"按钮或"New Page"创建新文档：

1. 输入文档名称
2. 选择创建位置（根目录或某个父文档下）
3. 开始编辑内容

3.3.2 块编辑基础

在 AFFiNE 中，每个内容元素都是一个"块"。常用操作包括：

添加块：在块末尾按 Enter 键创建新段落，或输入"/"调出块菜单

选择块：点击块左侧的拖拽手柄选中

移动块：拖拽块左侧的手柄到目标位置

删除块：选中块后按 Backspace 或 Delete 键

复制/粘贴块：选中块后使用 Ctrl+C/V

3.3.3 块类型

通过输入"/"可以调出块菜单，插入不同类型的块：

块类型	说明	用途
Text	普通文本段落	基础内容
Heading 1/2/3	一级/二级/三级标题	文档结构
Bullet List	无序列表	内容列举
Numbered List	有序列表	步骤说明
Todo	待办事项	任务清单
Toggle	可折叠列表	隐藏/显示内容
Quote	引用块	引用内容
Code	代码块	代码展示
Divider	分割线	分隔内容
Image	图片	图片插入
Callout	提示框	重要信息

3.4 白板模式使用

AFFiNE 支持在同一文档中切换文档模式和白板模式，或者直接创建白板页面。

3.4.1 创建白板

在左侧边栏点击"+" → “Canvas"创建白板页面，或者在文档中使用”/canvas"插入白板块。

3.4.2 白板工具栏

白板模式下的工具栏包含以下工具：

• 选择工具：选中并移动元素
• 文字工具：在画布上添加文本框
• 便签工具：创建便签
• 形状工具：绘制各种形状
• 画笔工具：自由绘制
• 连接器工具：绘制箭头和连接线
• 插入工具：插入图片、网页等

3.4.3 常用操作

添加便签：选择便签工具，点击画布创建，选择颜色和大小

添加文字：选择文字工具，点击画布输入文本

插入图片：选择插入工具 → 图片，可上传本地图片或粘贴网络图片 URL

缩放画布：使用鼠标滚轮缩放，或点击右下角的缩放比例

平移画布：按住空格键拖拽，或使用鼠标中键拖拽

3.5 数据库使用

3.5.1 创建数据库

在文档中输入"/database"创建数据库，或在白板中使用数据库组件。AFFiNE 提供两种创建方式：

全屏数据库：创建一个独立的数据库页面

内联数据库：在当前文档中嵌入数据库块

3.5.2 配置数据属性

创建数据库后，需要定义数据属性（列）：

1. 点击数据库右上角的"+"按钮
2. 选择属性类型
3. 输入属性名称

支持的属性类型包括：

属性类型	说明
Text	文本内容
Number	数字
Select	单选
Multi-select	多选
Date	日期
Checkbox	复选框
URL	网址链接
Email	邮箱地址
Phone	电话号码
Relation	关联其他数据库
Formula	公式计算

3.5.3 切换视图

数据库创建后，默认以表格视图展示。点击左上角的视图切换按钮可以切换到其他视图：

表格视图：适合详细查看和编辑数据

看板视图：适合按状态/优先级分组的任务管理

画廊视图：适合图片为主的数据库展示

日历视图：适合时间相关的任务规划

3.5.4 视图筛选与排序

每个视图支持独立的筛选和排序设置：

• 按属性筛选显示特定条件的记录
• 按一个或多个属性排序
• 保存视图设置，方便后续快速切换

四、进阶功能与最佳实践

4.1 双向链接与知识图谱

4.1.1 创建文档链接

在文档中输入[[可以快速搜索并链接到其他文档：

1. 输入[[调出文档搜索
2. 输入文档名称进行搜索
3. 选择目标文档

链接创建后，点击链接可以直接跳转到目标文档。

4.1.2 链接视图

创建多个文档链接后，可以生成链接视图（Linked View）来可视化展示文档之间的关系：

1. 在文档中输入/linked view
2. 系统会自动显示所有反向链接
3. 可以拖拽布局形成知识图谱

4.2 模板使用

4.2.1 创建模板

可以将常用文档保存为模板：

1. 创建好文档结构
2. 点击右上角"···"菜单
3. 选择"Save as Template"
4. 输入模板名称

4.2.2 使用模板

创建新文档时，可以选择使用模板：

1. 点击"+" → “From Template”
2. 选择需要的模板
3. 系统会基于模板创建新文档

4.3 标签管理

AFFiNE 支持为文档添加标签，便于分类和检索：

1. 在文档属性面板中添加标签属性
2. 为文档分配标签
3. 通过标签筛选快速找到相关文档

4.4 PWA 桌面应用

AFFiNE 支持 PWA，可以安装为桌面应用获得更好的体验：

1. 在浏览器中打开 AFFiNE
2. 点击地址栏右侧的安装图标
3. 确认安装

安装后的桌面应用支持：

• 独立的窗口运行
• 离线文档编辑
• 系统通知
• 更快的启动速度

4.5 数据导入导出

4.5.1 从 Notion 导入

AFFiNE 支持导入 Notion 导出的数据：

1. 在 Notion 中导出为 Markdown
2. 在 AFFiNE 中选择"Import"
3. 选择 Notion 格式
4. 上传导出的文件

4.5.2 数据导出

AFFiNE 支持导出为多种格式：

• Markdown（纯文本）
• PDF
• HTML

点击文档右上角"···"菜单 → "Export"选择导出格式。

4.6 团队协作

4.6.1 邀请成员

在工作区设置中可以邀请团队成员：

1. 进入工作区设置
2. 选择"Members"
3. 点击"Invite Member"
4. 输入成员邮箱发送邀请

4.6.2 权限管理

AFFiNE 支持细粒度的权限控制：

• Owner：工作区所有者，拥有全部权限
• Admin：管理员，可以管理成员和设置
• Member：普通成员，可以编辑共享内容
• Guest：访客，仅能查看被分享的内容

4.7 自托管 AI 配置

AFFiNE 支持集成 AI 功能，在自托管环境中可以配置自己的 AI 服务：

在 .env 文件中添加 AI 相关配置：

# AI 服务提供商（openai/anthropic 等）
AI_PROVIDER=openai

# API Key
AI_API_KEY=your-api-key

# API 基础 URL（可选，用于代理或自建服务）
AI_API_BASE_URL=https://api.openai.com/v1

配置后，AI 功能将在文档编辑、白板等场景中可用。

五、常见问题与解决方案

5.1 部署常见问题

Q：Docker Compose 启动后显示"服务暂时不可用"

A：这通常是首次启动时数据库初始化较慢导致的。等待 2-3 分钟后刷新页面重试：

# 查看日志确认服务状态
docker compose logs -f

Q：如何修改管理员密码

A：通过命令行重置：

docker compose exec affine reset-password

Q：如何升级到最新版本

# 停止服务
docker compose down

# 拉取最新镜像
docker compose pull

# 重新启动
docker compose up -d

5.2 使用常见问题

Q：如何恢复误删除的文档

A：AFFiNE 提供了回收站功能：

1. 在左侧边栏找到"Trash"
2. 找到误删除的文档
3. 点击"Restore"恢复

Q：数据库视图不显示数据

A：检查数据库属性配置：

1. 确认数据记录已添加
2. 检查视图筛选条件是否过于严格
3. 确认当前视图筛选的属性在数据中存在

Q：如何实现文档嵌套

A：AFFiNE 支持通过以下方式组织文档层级：

• 在左侧边栏拖拽文档到父文档下
• 在白板中嵌入子文档块
• 使用数据库的关系属性关联文档

5.3 性能优化建议

Q：数据量大时页面加载变慢

A：可以采取以下优化措施：

1. 定期清理回收站中的文档
2. 避免在单一文档中放置过多内容块
3. 合理使用数据库，避免单表数据量过大
4. 考虑分库部署，将不同工作区部署到独立实例

Q：内存占用过高

A：可以通过限制 Docker 资源使用：

# 在 docker-compose.yml 中添加
services:
  affine:
    deploy:
      resources:
        limits:
          memory: 4G

六、总结

AFFiNE 作为一款开源的知识管理平台，凭借其文档、白板、数据库三位一体的设计，为用户提供了 Notion + Miro 的完整开源替代方案。其本地优先的设计理念，让用户真正掌控自己的数据，无需担心隐私泄露。

通过本文的保姆级教程，读者应该已经掌握了：

1. 部署安装：使用 Docker Compose 快速部署私有化 AFFiNE 服务
2. 基础操作：文档编辑、白板使用、数据库管理
3. 进阶功能：双向链接、模板使用、团队协作、AI 集成
4. 最佳实践：数据组织、标签管理、性能优化

对于追求高效协作和数据自主的个人和团队，AFFiNE 是一个值得关注和投入的工具。其开源特性意味着可以根据自身需求进行定制开发，完全掌控数据安全。

建议在使用 AFFiNE 时：

• 从个人知识管理开始，逐步扩展到团队协作
• 建立统一的文档组织结构和命名规范
• 善用模板功能提高文档创建效率
• 定期整理和归档文档，保持知识库整洁

---

© 版权归无边界科技所有，版权所有。