AFFiNE 自托管部署实战：开源 Notion 替代品的本地优先知识库搭建

1. 为什么大家都在找 Notion 的替代品1.1 从一次团队协作翻车说起去年我帮一个十来人的小团队做知识库迁移原本用的是 Notion。刚开始大家都觉得挺香页面嵌套、数据库视图、看板切换几乎什么都能塞进去。但用了半年问题就来了免费版块数量限制、协作人数一超就得升级、国内访问偶尔抽风、导出 Markdown 之后格式全乱。最要命的是有一次团队想批量整理历史文档发现数据锁在云端想本地备份一份完整结构都费劲。那次之后我就开始认真找替代方案。找了一圈发现市面上打着Notion 替代旗号的产品不少但真正能做到开源、可自托管、块级编辑、数据库视图这几样都齐活的其实没几个。AFFiNE 是我用下来觉得最接近下一代这个定位的一个——它不是简单抄 Notion 的界面而是把文档、白板、数据库三种形态揉在同一个空间里而且核心代码开源能自己部署。这篇文章我不打算写成产品说明书而是把我从选型、部署、实际用到踩坑的整个过程摊开讲。如果你也在纠结要不要从 Notion 迁出来或者想给团队搭一套自己能掌控的知识库下面的内容应该能帮你少走不少弯路。1.2 先搞清楚你要的到底是替代还是补充很多人一上来就说我要换掉 Notion但实际需求可能只是我想要一个能本地部署的文档工具。这两个诉求差别很大。Notion 的核心竞争力从来不是单一功能而是块编辑器 数据库 协作 模板生态这一整套组合拳。你要替代它就得想清楚自己最离不开哪一块如果你主要用它的文档编辑和页面嵌套那替代品只要块编辑器做得顺就行如果你重度依赖数据库视图表格、看板、日历、画廊那替代品的数据库能力必须过硬如果你还需要多人实时协作 权限管理那自托管方案的部署复杂度会直接上一个台阶。AFFiNE 的定位比较有意思它把文档和白板放在同等重要的位置数据库能力也在逐步补齐。所以它更适合那种既要写文档、又要画图梳理思路、还想把两者关联起来的场景。纯做表格管理的团队用起来可能会觉得数据库这块还不够成熟。提示选型之前先列一张我每周实际用到的功能清单按使用频率排序前五项才是你真正不能妥协的。剩下的都是锦上添花。2. AFFiNE 到底是个什么东西2.1 一句话说清它的核心形态AFFiNE 可以理解成一个文档 白板 数据库三合一的本地优先工作空间。你打开一个页面既可以在里面写富文本也可以随时切到白板模式画流程图、贴便签、连线还能建数据库表格做任务管理。这三种形态共享同一套底层数据模型所以文档里的内容可以直接拖到白板上白板上的卡片也能关联到数据库条目。它和 Notion 最大的区别在于**本地优先Local-first**这个设计理念。简单说就是你的数据首先存在本地联网只是用来同步和协作。这意味着即使断网你照样能编辑即使官方服务挂了你的数据也不会丢。对于我这种被云端服务坑过的人来说这一点吸引力非常大。2.2 开源这件事意味着什么AFFiNE 的核心代码是开源的你可以自己拉代码部署也可以用它提供的托管服务。开源带来的实际好处有几个数据自主所有内容存在你自己的服务器或本地不用担心服务商跑路或者突然改收费策略可定制界面、功能、集成方式都能按团队需求改可审计代码摆在那里安全性自己能把控社区生态插件、模板、主题这些会慢慢长出来。当然开源也有代价。自托管意味着你得自己维护服务器、处理升级、备份数据。如果你团队里没有懂运维的人这部分成本要提前算进去。2.3 和 Notion 的功能对照能力维度NotionAFFiNE块编辑器成熟生态丰富已具备细节还在打磨数据库视图表格/看板/日历/画廊齐全基础视图可用高级视图逐步补齐白板/画布无原生白板原生支持与文档深度打通本地优先否强依赖云端是本地存储 可选同步自托管不支持支持开源否是协作成熟可用实时性持续优化模板生态极其丰富社区模板在增长从这张表能看出来AFFiNE 的差异化优势集中在白板融合和本地优先 开源这两点上。如果你恰好需要这两样它就是很值得试的选择如果你只想要一个和 Notion 一模一样的克隆那可能会失望。3. 自托管部署从零搭一套自己的知识库3.1 部署前的环境准备我用的是一台 2 核 4G 的云服务器系统是 Ubuntu 22.04。这个配置跑 AFFiNE 单实例够用但如果团队人数超过 20 人建议上 4 核 8G。部署方式我推荐用 Docker Compose原因是依赖组件比较多数据库、缓存、对象存储手动装容易漏。先确认服务器上装好了 Docker 和 Docker Composedocker --version docker compose version如果没装用官方脚本装一下就行。装完之后建一个工作目录比如/opt/affine后面所有配置都放这里。3.2 核心配置文件怎么写AFFiNE 的 Docker 部署需要一个 compose 文件里面通常包含这几个服务AFFiNE 主服务、PostgreSQL 数据库、Redis 缓存。下面是我实际用的精简版配置去掉了不必要的注释services: affine: image: ghcr.io/toeverything/affine:stable container_name: affine restart: unless-stopped ports: - 3010:3010 environment: - AFFINE_CONFIG_PATH/root/.affine/config - REDIS_SERVER_HOSTredis - DATABASE_URLpostgres://affine:affinepostgres:5432/affine volumes: - ./data/config:/root/.affine/config - ./data/storage:/root/.affine/storage depends_on: - postgres - redis postgres: image: postgres:16 container_name: affine-postgres restart: unless-stopped environment: - POSTGRES_USERaffine - POSTGRES_PASSWORDaffine - POSTGRES_DBaffine volumes: - ./data/postgres:/var/lib/postgresql/data redis: image: redis:7 container_name: affine-redis restart: unless-stopped volumes: - ./data/redis:/data几个关键点解释一下端口映射主服务默认监听 3010我映射到宿主机同一个端口方便后面配反向代理数据卷config、storage、postgres、redis 四个目录都要挂出来不然容器一删数据就没了数据库连接串格式是postgres://用户:密码主机:端口/库名这里的postgres是 compose 里的服务名Docker 内部会自动解析镜像标签用stable比用latest稳避免某天拉到一个半成品版本。3.3 启动与首次访问配置写好后在目录里执行docker compose up -d第一次启动会拉镜像视网络情况可能要等几分钟。启动完成后用docker compose ps看一下三个容器是不是都处于 running 状态。然后浏览器访问http://你的服务器IP:3010应该能看到注册页面。第一次注册的账号会自动成为管理员。注册完之后建议立刻做两件事一是进设置里把默认语言切成中文二是配置一下备份策略。注意默认配置下没有开启邮件验证注册接口是开放的。如果服务器暴露在公网一定要在反向代理层加访问控制或者部署完立刻关掉注册入口。3.4 配一个域名和 HTTPS直接用 IP 端口访问体验很差而且没有 HTTPS 浏览器会各种警告。我用 Nginx 做反向代理配置大概是这样server { listen 443 ssl; server_name your-domain.com; ssl_certificate /path/to/cert.pem; ssl_certificate_key /path/to/key.pem; 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; } }最后两行是给 WebSocket 用的AFFiNE 的实时协作依赖它不加的话多人同时编辑会出问题。证书可以用 Lets Encrypt 免费申请这里不展开。4. 实际使用文档、白板、数据库怎么配合4.1 文档编辑的实操体验AFFiNE 的编辑器交互和 Notion 很像输入/唤出块菜单支持标题、列表、代码块、引用、分割线这些基础块。我实际用下来日常写文档完全够用响应速度也不错。几个我觉得比 Notion 顺手的地方块拖拽更自由可以直接把一段文字拖到白板区域变成卡片双向链接输入[[就能引用其他页面反向链接面板会自动汇总本地保存无延迟断网状态下编辑恢复网络后自动同步不会像某些云端工具那样卡在保存中。需要适应的地方也有快捷键体系和 Notion 不完全一致比如 Notion 里CmdShift7是有序列表AFFiNE 里可能对应别的组合。建议花半小时把设置里的快捷键列表过一遍。4.2 白板模式这才是它的杀手锏白板是我用 AFFiNE 最频繁的功能。举个实际场景团队要做季度规划我先建一个白板页面左边贴目标便签中间画流程箭头右边放负责人卡片。然后把这个白板直接嵌到文档里文档负责写详细说明白板负责呈现全局。白板支持的操作包括自由绘制、形状、连线、文本、便签从文档拖入内容块框选多个元素成组无限画布缩放。我试过用它替代 Figma 做简单的流程图和架构草图对于非设计岗的日常需求完全够用。复杂 UI 设计还是得回专业工具但画个思路图这种场景切来切去反而更累。4.3 数据库视图的当前能力数据库这块要客观说AFFiNE 目前还不如 Notion 成熟。基础表格视图、看板视图能用字段类型支持文本、数字、日期、单选、多选、人员这些。但像 Notion 那种复杂的公式字段、关联数据库、rollup 汇总AFFiNE 还在逐步补齐。我的用法是把 AFFiNE 的数据库当轻量任务管理用比如记录待办、跟踪内容排期。真正复杂的数据分析还是丢给专业工具。这样定位反而清晰不会因为期待过高而失望。数据库能力当前状态适用场景表格视图可用任务清单、内容排期看板视图可用流程管理、状态跟踪字段类型基础齐全日常记录够用公式字段部分支持简单计算关联/汇总开发中暂不建议依赖5. 踩过的坑和排查经验5.1 容器启动后访问白屏第一次部署完浏览器打开是白屏控制台报一堆资源加载失败。排查下来是反向代理没配 WebSocket导致前端拿不到实时连接。加上前面 Nginx 配置里那两行 Upgrade 头就好了。还有一种白屏是数据库没连上。用docker compose logs affine看日志如果出现connection refused之类的报错检查 postgres 容器是不是正常起来了以及连接串里的密码和 postgres 服务里设的是否一致。5.2 数据备份怎么做才靠谱自托管最大的风险就是数据丢。我的备份策略是两层第一层每天凌晨用pg_dump导出 PostgreSQL 数据存到另一个目录第二层每周把 storage 目录和数据库导出文件一起打包同步到对象存储或另一台机器。具体命令docker exec affine-postgres pg_dump -U affine affine backup_$(date %F).sql恢复的时候反过来先建库再导入。这个流程我实际演练过一次能完整恢复心里才踏实。5.3 常见问题速查表现象可能原因处理方式白屏WebSocket 未代理检查 Nginx Upgrade 头登录后一直转圈数据库连接失败看日志核对连接串多人编辑冲突Redis 未启动确认 redis 容器状态上传图片失败storage 目录权限检查挂载目录读写权限升级后打不开数据库迁移未完成看日志等待迁移勿中途重启内存占用飙升容器未限制资源compose 里加 mem_limit5.4 升级的正确姿势开源项目迭代快升级是常事。我的做法是先备份数据库和 storage拉新镜像docker compose pull停旧容器docker compose down起新容器docker compose up -d盯日志看数据库迁移是否完成。注意跨大版本升级前一定先看官方 release notes有些版本会改数据表结构迁移不可逆。生产环境建议先在测试机跑一遍。6. 它适合谁不适合谁6.1 推荐尝试的几类人注重数据自主的团队不想把核心知识库放在别人服务器上需要文档 白板联动的人产品、设计、研发梳理思路时特别顺手有运维能力的小团队能自己维护 Docker 服务享受开源带来的自由度想研究本地优先架构的开发者代码开源是很好的学习样本。6.2 暂时不建议入坑的情况团队完全没有技术运维自托管的维护成本会变成负担重度依赖复杂数据库公式这块能力还没补齐需要极其成熟的模板生态Notion 的模板库短期内难以被超越对实时协作稳定性要求极高大规模并发场景还在优化中。6.3 我的迁移策略我没有一刀切全迁而是新项目用 AFFiNE老项目留在 Notion。等 AFFiNE 的数据库能力再成熟一些再逐步把历史内容导过来。导出的时候用 Markdown 格式虽然格式会有损失但核心文字内容能保住。这个渐进式迁移的好处是既能享受新工具的优势又不会因为一次性迁移出问题而影响正常工作。踩坑的成本被控制在可接受范围内。7. 几个提升效率的小技巧用了一段时间攒了几个比较实用的小习惯分享出来。第一个是善用白板做入口页。我把团队所有重要文档的链接都贴在一张白板上按项目分区新人进来一眼就能看到全貌。比传统的目录页直观得多。第二个是给数据库字段起名要克制。字段一多表格就变得难维护。我现在的原则是能用一个字段表达的绝不拆成两个。第三个是定期清理 storage 目录。删除的页面附件不会自动从磁盘清掉时间长了会占空间。我一般每季度手动检查一次。第四个是善用双向链接做知识网络。写文档时随手[[引用相关页面时间长了会自动形成一张关系网找东西比搜索还快。最后再分享一个小技巧AFFiNE 的快捷键可以在设置里自定义我把最常用的几个改成了和 Notion 一致的组合迁移过来几乎零学习成本。这个细节虽然小但对天天用的人来说能省下不少适应时间。