AFFiNE Docker自部署教程：打造文档白板数据库三合一私有知识库

1. AFFiNE 凭什么值得折腾一次自部署1.1 这工具到底是个啥文档、白板、数据库是怎么“合体”的先交代一下背景。AFFiNE 这个项目我最早是在 GitHub 上刷到的定位是“Notion Miro 的开源替代品”。翻译成人话就是它想同时干掉你笔记软件里的文档编辑、思维导图/流程图那块白板以及数据表格Database这三个独立场景。以前你要在 Notion 里写文档、去 FigJam 或 Miro 里画架构图、再用 Airtable 或者 Excel 管结构化数据三个工具来回切标签开一堆窗口摆得密密麻麻。AFFiNE 想做的是让这三件事发生在同一个文件、同一个工作区里。它的核心单位是一个叫“块”Block的东西。你写的内容天然是块拖拽进来的白板画布也是块数据库表格同样是块。块和块之间可以直接嵌套、引用、内嵌。所以它的文档可以随时变成白板里的便签白板里的内容也可以反向引用回文档数据库的一行记录点进去又是一篇完整的富文本页面。这个“万物皆块”的底子跟 Notion 的 block 模型很像但 AFFiNE 把白板画布做成了跟文档同级的“一等公民”这是它区别于 Notion 最狠的一点。1.2 为什么要用 Docker 自部署而不是直接开个云服务先说 AFFiNE Cloud 官方服务。它也在线可用注册就能用。但我的选择是 Docker 自部署原因不复杂第一数据自己握着。笔记这玩意儿一旦写多了就是个人资料库我不想它只存在某个我不完全可控的云服务里。第二离线可用。自己部署在局域网里没外网的时候照样看笔记、画白板、改数据库。第三版本可控。官方服务升级是全自动的偶尔一次大版本变更界面变化很大自部署我愿意什么时候升就什么时候升甚至能固定在某一个版本不折腾。对普通用户来说自部署听起来像“技术宅专属”但 AFFiNE 官方其实把门槛已经降得比较低了——只要你能装 Docker跑一条命令就能起来。我有台 NAS常年开着给它分一个端口就成了私人知识库。家里其他设备直接浏览器访问手机平板也不受影响。如果你手头没有 NAS一台常年开机的旧电脑、云服务器或者跑 VMware/软路由的小主机都能胜任。1.3 哪些人适合切过来哪些人其实没必要换先说结论不是所有人都适合从 Notion 切到 AFFiNE这里不劝退也不吹捧先说适用人群。适合切过来的人我认为有三类第一类是重度文档白板用户比如画系统架构、做产品原型、梳理流程这类人最受益因为白板和文档不割裂了第二类是对数据自主性敏感的人笔记和工作资料不想放第三方平台的第三类是喜欢折腾、愿意把工具链打磨成自己形状的人AFFiNE 开源、插件机制相对活适合理想主义的工具党。而不适合立刻换的则是这些情况你重度依赖 Notion 的第三方生态比如各种嵌入组件、Chrome 插件、自动化流程AFFiNE 目前生态还弱不少你的协作团队已经全员 Notion迁移成本比工具差异还大你需要非常复杂的数据库关系、跨表格公式和权限系统AFFiNE 的 database 还达不到 Notion 的完成度。诚实地讲我最后卸载 Notion是因为我的使用场景刚好是第一类而不是说 AFFiNE 全面碾压。后面我会详细讲清楚它哪方面强、哪方面弱。2. Docker 部署 AFFiNE 的完整实操2.1 镜像与部署方案的选择AFFiNE 的 Docker 镜像官方比较推荐的是ghcr.io/toeverything/affine这个镜像是包含前端静态资源和服务端的整体镜像。它允许你选择是否自带数据库。AFFiNE 的数据库依赖主要有两块一个是 PostgreSQL用来存结构化数据另一个是 Redis用来做缓存、消息队列一类的工作。有的镜像版本把 PostgreSQL 内置在镜像里有的则需要你自己挂一个外部数据库。这里我给出一个建议如果你只是自己用、最多小圈子几个人协作直接选择官方镜像的默认启动方式最省心。它会自动以 SQLite 或者内置 PostgreSQL 的方式运行你不需要额外安装任何数据库组件。如果你要正经生产化使用、数据量大、多人并发那就得单独部署 PostgreSQL 和 Redis通过环境变量把 AFFiNE 指向外部数据库。我个人第一轮部署走的是官方默认因为场景就我一个人写笔记和画图数据量远没到需要独立 PostgreSQL 的地步。这一版起好后跑了一周很稳。后来我为了折腾数据库课程里学的那套备份恢复逻辑才把数据迁到了外部 PostgreSQL 上这个后面一起说。2.2 docker-compose 配置与数据持久化用 Docker 部署最重要的就是别把容器当成“一次性的”。容器随时可能删掉重建所以数据必须放在宿主机目录里挂载进容器这是所有自部署服务的铁律。AFFiNE 也不例外你需要把它的数据目录、配置文件都持久化。下面是我的 docker-compose.yml我直接贴出来。这段配置适配的是 AFFiNE stable 版本如果你要固定版本把image改成具体的 tag 比如ghcr.io/toeverything/affine:stable-0.17.1即可。services: affine: image: ghcr.io/toeverything/affine:stable container_name: affine restart: unless-stopped ports: - 3010:3010 volumes: - ./affine_data:/root/.affine environment: - AFFINE_SERVER_PORT3010 - AFFINE_SERVER_HOST0.0.0.0 - AFFINE_CONFIG_PATH/root/.affine/config # 以下两项看你的部署方式默认可以不开 # - AFFINE_SERVER_EXTERNAL_URLhttps://notes.example.com # - AFFINE_SERVER_AUTHENTICATION_ENABLEtrue重点解释几点AFFINE_SERVER_PORT3010是 AFFiNE 默认监听端口。宿主机端口3010:3010左侧那个 3010 可以改成别的比如8080:3010避免和你机器上其他服务冲突。AFFINE_CONFIG_PATH指向持久化配置目录我把整个/root/.affine都挂出来了这样数据库文件、附件、用户配置全都在宿主机上的./affine_data里躺着。后续不管是升级容器还是备份恢复直接操作这个目录即可。写完配置后在docker-compose.yml同目录下执行docker compose up -d然后访问http://你的服务器IP:3010就能看到 AFFiNE 的注册页。注册第一个账号这个账号默认就是 workspace owner拥有全部管理权限。我第一次用的时候没有踩任何坑从拉镜像到注册账号耗时大约三分钟这个项目镜像做得还是比较干净的。2.3 部署后的配置检查与反向代理注意事项启动完成后先别急着往里写笔记建议先做三件事。第一确认容器日志没有报错。执行docker logs -f affine重点看有没有connected、listening之类的关键词如果刷出大量ECONNREFUSED或者failed to connect to redis说明你用了外部数据库但环境变量没配对。默认启动方式下日志一般很安静。第二设置反向代理。如果你只在局域网里用直接 IP端口访问就够了。但如果你想在外网访问、或者想用 HTTPS 加密传输最好在前面加一层 Nginx 或者 Caddy。我用 Nginx 配了一个子域名转发到 3010 端口注意要同时配置 WebSocket 转发因为 AFFiNE 的实时协作依赖 WebSocket。Nginx 里面核心就两行proxy_pass http://127.0.0.1:3010; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade;少了Upgrade这两行页面能打开但白板拖拽和协作功能会时好时坏这个坑我踩过。第三立刻备份一次。直接把affine_data目录打包存到别的地方就行不需要先装任何备份插件tar -czf affine_backup_$(date %Y%m%d).tar.gz ./affine_data这个习惯很重要。自部署服务最怕的就是“数据没了”一次备份后面所有折腾都有了底气。3. 三合一功能拆解文档、白板、数据库到底怎么协同3.1 文档与数据库的深度联动AFFiNE 的编辑器体验说实话刚上手会有点“空”。工具栏不花哨排版快捷键是主流 Markdown 风格打#空格表示一级标题-表示无序列表[]表示待办事项该有的都有不会觉得缺胳膊少腿。真正拉开差距的是它把“数据库”做成了文档里的内嵌块而且这个内嵌块可以跟页面双向联动。打个比方我以前在 Notion 里管读书笔记是搞一个 database每个条目填书名、作者、状态、评分、笔记链接字段。在 AFFiNE 里我同样建了一个叫“阅读清单”的 database 块但每个条目的正文区域不是靠文本字段糊弄过去的而是直接点进去就是一个独立页面这个页面里我可以写长文、插入白板画线、再挂几个子数据库。这个结构用 Notion 也能七七八八实现但 AFFiNE 的“轻”体现在它不是先有 database 再关联页面而是 database 本身就是从页面里长出来的双向跳转几乎没有层级感。另外AFFiNE database 支持行内编辑。你可以在一篇笔记中间插入一个 database 块往里面添加数据然后继续写下面的内容。整个文档的阅读流不会被一个巨大的表格打断这个体验比 Notion 里那种“一整个数据库页面”要更接近写作的自然节奏。3.2 无限白板Edgeless的实际用法白板部分AFFiNE 管它叫 Edgeless Mode。它不是简单的“画布上贴便签”而是允许你把文档块直接丢到无限画布上自由摆放、连线、分组。我实际用下来最舒服的场景是产品需求梳理。举个例子我在做一个小工具的前期设计会新建一个白板先从资料文档里把用户诉求、竞品分析、技术约束这几段文字分别框选拖到白板上变成三块便签。然后在便签之间拉箭头标出关联和冲突。再在旁边画一个简单的流程图表示数据流转路径。整个过程不需要切窗口白板右侧还能继续开一个数据库块记录每个交互点的状态待做/进行中/已完成。这放在以前我至少要开三个标签页才能把这件事说清楚。另外提一句白板里的元素是可以直接跟文档块联动的。你双击白板上的便签如果它源自某个文档块可以直接跳转回原文你在文档里的修改返回白板后便签内容也会同步更新。这个特性不是很起眼但真正写方案的时候很好用——你不用维护两套内容改文档就自动改白板。3.3 “三合一”在真实工作流里怎么组合很多人问三合一到底怎么合我用一个自己的真实工作流来举例。我维护了一个“家庭自托管服务清单”的工作区里面有一个数据库记录所有我部署的服务字段包括服务名、端口、是否关键服务、更新频率、备注。每个记录点进去就是一篇完整的服务文档部署命令、配置文件、踩坑记录。但这篇文档的顶部我插入了一个白板块上面画了这个服务的架构图。以前这个架构图我要么用 draw.io 画完导出图片传上来要么干脆不放。现在直接在文档里画改的时候双击就能编辑。数据库、文档、白板三个块在同一个页面里各司其职各自又能跳转到自己的完整视图。说白了“三合一”不是三个功能强行拼在一个按钮里而是三种媒介可以互相嵌入、自由穿梭。这个体验Notion 目前给不了。4. 从 Notion 迁移过来的真实对比和取舍4.1 数据库能力和 Notion 的差异既然标题里提到“数据库”这块必须重点说。AFFiNE 的 database block基础能力是有的支持多视图表格、看板、画廊支持筛选、排序、分组支持多种字段类型文本、数字、单选、多选、日期、人员、URL、附件还支持公式字段和 relation 关联。我自己用它管理了不少结构化数据比如硬件设备清单、文章选题库、项目待办日常使用完全够。但真跟 Notion 比差距也在。Notion 的 database 经过这么多年打磨关联数据库relation rollup非常成熟可以跨页面拉数据、聚合统计。AFFiNE 的 relation 目前还比较基础跨 workspace 关联几乎没有rollup 的含义需要自己手动选择字段去汇总公式函数也不如 Notion 丰富。如果你的需求是“几十个数据库互相引用、自动汇总统计、按状态驱动工作流”AFFiNE 目前还是不够的。不过 AFFiNE 有一个点我很喜欢database 可以直接写 Markdown 表格然后一键转换。你贴一段 Markdown 表格进页面右上角会提示你 “Turn into database”点一下静态表格瞬间变成可筛选、可排序的数据库块。这个入口对从 Typora 或者其他 Markdown 工具迁移过来的人非常友好省得手工重建表格。4.2 迁移过程的经验教训我迁移的时候没用什么自动导入工具因为我的 Notion 内容结构实在太乱了——有的笔记是纯文本有的里面有大量 embed 组件有的 database 字段类型跟 AFFiNE 不兼容。硬用官方导入工具出来一堆排版错乱还不如人工重新整理。具体怎么迁的我的策略是“按数据优先级分三批”。第一批把最重要的结构化数据库迁移过去比如文章管理库、硬件清单库这些数据的字段要提前在 AFFiNE 里重新建好手工录入。第二批把长文笔记导出成 Markdown再批量导入 AFFiNE。AFFiNE 支持 Markdown 导入表格、代码块、图片链接基本能保留虽然偶尔会有格式偏一点但整体可用。第三批那些已经失去时效性的碎片笔记、临时剪藏我直接留在 Notion 里归档不迁了。这里有个操作细节从 Notion 导出 Markdown 时图片默认是存成外部链接的导入 AFFiNE 后图片可能加载不出来。我的办法是先把导出的 Markdown 里的图片下载到本地再手动上传到 AFFiNE 对应正文里。虽然费点事但数据彻底脱离第三方依赖符合自部署的初衷。4.3 什么时候该保留 Notion什么时候可以卸载实话实说我最终卸载 Notion 是有前提的。一是我的笔记库已经整体迁到 AFFiNE二是我不依赖 Notion 的多人协作和第三方生态三是 AFFiNE 没有踩到我的刚需功能雷区。如果你跟我情况类似可以试试卸载后的体验你自己掌握数据、界面没有多余的广告和推荐、打开速度快、离线也能用。但我也保留了几个 Notion 使用的习惯算是给读者的建议如果你的团队协作根深蒂固建议保留 Notion 作为协作文档中心AFFiNE 做个人知识库和草图本两者各管一段。如果你重度使用 Notion 的模板社区和 embed 生态先别急着搬等 AFFiNE 生态再长一长。工具服务于人不是人服务于工具这条我始终记着。5. 常见问题排查和避坑实录5.1 部署层面的典型问题镜像拉取慢或失败。ghcr.io 的镜像在部分地区访问质量不太稳定这是很多人第一次部署失败的根源。解决办法通常是用代理或者配置镜像加速器。不过我更推荐的做法是固定一个版本号比如stable-0.17.x拉取一次后保存成本地 tar 包之后再部署就不依赖外网了。执行docker save把镜像导出放到 U 盘或者 NAS 备份以后重建秒装。端口被占用或外网访问不了。先确认宿主机端口有没有被占用再确认防火墙和安全组有没有放开 3010或你映射的端口。很多时候“外网访问不了”不是 AFFiNE 的问题而是云服务器安全组没放行端口这个顺序别搞反。局域网内访问没问题但外网访问不了九成是路由 NAT 或防火墙问题。容器重启后数据丢了。这种问题出现一次就该骂自己挂载卷一定写在 volumes 里了吗宿主机目录权限对吗我之前有一次在 compose 文件里忘了写 volumes结果重装容器后 workspace 空空如也幸好备份还在。记住容器是牛马数据才是主人。5.2 使用层面的体验问题第一个常见问题白板画布卡顿。当白板里塞了几百个元素或者画布尺寸拉到很大的时候某些性能一般的设备上拖动画布会有明显掉帧。这不是 bug而是 Canvas 渲染的固有瓶颈。解决办法是别把一张白板当万能桶一个工作区可以建多个白板按主题拆分。第二个问题数据库字段类型选错导致后期返工。AFFiNE 目前对字段类型的修改限制比较严格比如你建了一个文本类型的字段后面想改成单选类型目前是不支持直接改的只能新建字段再手工迁移数据。所以建议建表前想清楚字段类型宁可先多建两个字段测试。第三个问题多人协作时的冲突。虽然 AFFiNE 支持实时协作但自部署单机场景下我一般只保留一到两个协作者因为同时编辑同一个块偶尔会出现版本冲突。不严重但对于多人强协作的场景体验确实不如 Notion 的多人模式成熟。小团队用用没问题二三十人的并发编辑就要谨慎了。5.3 我的几个自用建议最后分享几条我折腾下来最想对后来人说的话。不要一上来就追求“把所有笔记都迁进去”。先把 AFFiNE 当成第二个草稿本用两周感受一下文档块、白板和数据库在你真实工作流里是不是真的顺滑。顺手了再规划迁移不顺手就继续留在 Notion这不丢人。备份一定要自动化。手动备份最大的问题是容易忘一忘就容易出事。我后来写了一个简单的 cron 定时任务每天凌晨打包affine_data目录保留最近 7 份压缩后推送到另一块硬盘。整个过程没有任何交互我唯一需要做的事是每个月抽检一次备份文件能不能正常解压。多利用 AFFiNE 的分享链接。自部署的 AFFiNE 支持生成公开分享链接可以做临时的对外展示用不需要对方注册账号。我不太希望把数据发到别人的服务器但如果是临时给朋友看一份方案、给同事提一个流程草案这个功能非常香。我在实际使用中还发现AFFiNE 的移动端适配比预期好。浏览器直接访问跟桌面端差距不大虽然官方也在推客户端但我一贯的原则是能浏览器的服务不装客户端少一个程序多一份清爽。对我这种重度文档白板数据库用户来说AFFiNE 用 Docker 自部署这套组合拳目前是最顺手的方案。如果你的需求跟我类似建议直接照着上面的流程部署一套试试成本很低收获可能超出预期。