我最早注意到 AFFiNE是在一个讨论“能不能彻底离开 Notion”的帖子里。当时评论区吵得很凶有人点名 AFFiNE说它是“笔记 白板 数据库”三合一的开源替代品还支持 Docker 自托管也有人说它只是概念唬人离 Notion 的成熟度还差得远。我那时正好处在对 Notion 的付费订阅、云存储和联网使用越来越不满的状态就顺手把这项目记了下来。真正让我决定动手部署的是一次离谱的“断网五小时”。那五小时里我写不了笔记、查不了个人数据库、连一份已存档的表格都打不开——因为所有东西都在 Notion 的服务器上。也就在那天晚上我开始认真搜 AFFiNE 的 Docker 部署方案折腾完以后我不仅把 Notion 卸载了还顺带把家里那台吃灰的 NAS 盘活了。如果你也想找一个能把数据放在自己手里、试用起来不折腾、兼顾文档编辑和可视化的笔记工具那这篇 AFFiNE 部署实操可以从头到尾帮到你。我会把 Docker 部署流程、自托管时的存储选型、从 Notion 迁移的坑以及我踩过的几个典型问题都写明白。1. AFFiNE 到底是什么为什么值得自托管AFFiNE 不是一个简单的“开源版 Notion”。它最大的特点是在一套编辑器里把传统文档、无限画布白板、结构化数据库三种形态彻底打通了。Notion 也支持数据库嵌入、也有所谓的“视觉化能力”但它本质还是“页面套页面”AFFiNE 则更像一块无限大的桌面既能在上面写字又能把内容变成卡片拖来拖去。1.1 一个页面三种形态文档、白板、数据库怎么融合AFFiNE 的核心模型是“块”Block。你在页面上写下的每一段文字、每张图片、每个列表底层都是一个块这些块在普通页面模式下像 Notion 一样按顺序排列方便线性阅读和书写。当你把页面切成“画布模式”Edgeless时所有块会变成可以自由拖动的卡片卡片之间还能用连线建立关系这就成了白板。真正有意思的是数据库块。在文档里插入一个 database block就能像 Notion 那样建表格、看板、日历、列表等视图。但它不是孤立的数据库同一个数据库卡片可以被嵌入白板然后与流程图节点连线。比如我日常做一个项目复盘左边用白板画时间线和问题树右边挂一个“任务数据库”每个任务卡片直接跟白板上的流程节点连接。这种体验在 Notion 里需要来回跳转在 AFFiNE 里是同一块画布上的事。数据库本身的功能也足够日用支持自定义属性类型文本、数字、勾选、日期、单选、多选等支持筛选、排序、分组基本覆盖 Notion 日常 90% 的数据库操作。它目前缺少高级汇总公式和更复杂的关联视图但对于个人笔记、项目任务、阅读清单、物品管理这类轻量结构化需求已经能打。1.2 为什么我最终选择自托管方案Notion 体验是好但它有几个硬伤第一数据全部在人家云端本地没有完整离线文件上次断网那事就是教训第二工作区一个人用也得按订阅付费年费也不算便宜第三数据格式不开放导出虽然方便但总让人觉得被锁在里面。AFFiNE 走的是开源 自托管路线。我可以用 Docker 把它部署在自己的 VPS 或 NAS 上数据落在我自己的磁盘里备份是我的事隐私也是我的事。升级可以自己控制想停就停想迁就迁。再加上 Docker 的容器化部署方式比直接装一个二进制服务要干净得多升级回滚都容易。我身边不少朋友已经在自托管各种服务了比如本地知识库、向量数据库、大模型推理服务现在又多了个 AFFiNE。这其实是一种趋势工具越来越轻量自托管的成本越来越低单个服务部署难度已经降到“会看日志就能玩”的程度。2. Docker 部署 AFFiNE 的完整流程含参数说明AFFiNE 的部署方式现在对新手友好很多了。官方提供了一体化镜像也就是说前端页面、后端接口、WebSocket 这些服务被打进同一个容器里不需要像老版本那样分别拉 three 个镜像手动连。下面这份流程我跑过不止一次照着走基本不会出问题。2.1 部署前要准备什么先说硬件。个人使用场景下一台 2 核 4G 的 VPS 或者任意一台 NAS、旧电脑都能跑起来。内存低于 2G 会比较吃力毕竟容器里除了服务本身还要跑数据库进程。我自己先在 2G 内存的机器上试过能启动但打开白板大文件时明显卡顿后来切到 4G 内存后流畅了很多。系统环境方面我是在 Linux 服务器上部署的装了 Docker 和 Docker Compose 插件。如果你的机器是 Windows 或 macOS装一个 Docker Desktop 也能跑不过建议给 Docker Desktop 分配不少于 4G 内存。可以用以下命令确认版本docker --version docker compose version这一步不是可有可无因为 AFFiNE 的 compose 文件里用到了比较新的 compose 语法老版本插件可能解析不了。另外一个容易被忽略的准备项是镜像源。AFFiNE 的 Docker 镜像存在 GitHub Container Registryghcr.io在国内网络环境下拉取会非常慢甚至直接超时。我的解决办法是在 Docker daemon 配置里加镜像加速器把 ghcr.io 的流量走加速节点这个体感差距非常大。配置完记得重启 Docker 服务再继续。2.2 docker-compose 配置与关键容器我部署时用的是官方仓库里的 compose 文件只改了端口和数据目录。为了让你理解每个配置的作用这里贴一份简化但可用的版本services: affine: image: ghcr.io/toeverything/affine:stable container_name: affine restart: unless-stopped ports: - 3010:3010 volumes: - ./affine_data:/app/data environment: - AFFINE_SERVER_PORT3010 - AFFINE_SERVER_HOST0.0.0.0 - AFFINE_SERVER_PATH/app/data/.affine - AFFINE_SERVER_ENABLE_SENTRYfalse - AFFINE_SERVER_TELEMETRYfalse healthcheck: test: [CMD, curl, -f, http://localhost:3010] interval: 30s timeout: 10s retries: 5先说镜像版本。我用的是stable标签代表稳定版主线。如果你想要最新功能和更好的第三方集成可以换成canary或对应版本号但生产和个人长期使用我建议固定稳定版避免升级带来破坏性变化。再说数据卷。./affine_data:/app/data这行是核心中的核心。AFFiNE 会把页面数据、附件元数据、内置 SQLite 数据库文件都写进容器的/app/data目录映射到宿主机后容器无论怎么删、怎么重建数据都不会丢。我见过太多人栽在这里容器一升级没映射数据卷所有笔记全没了。配置完 compose 文件后务必ls -al看一眼宿主机上是否真的生成了数据目录。最后说环境变量。AFFINE_SERVER_PORT和AFFINE_SERVER_HOST指定容器监听端口和地址默认0.0.0.0表示允许宿主机外部访问。AFFINE_SERVER_ENABLE_SENTRY和AFFINE_SERVER_TELEMETRY一个控制错误上报、一个控制遥测统计我在自托管时都关掉了纯属个人隐私偏好。不同 AFFiNE 版本的环境变量可能略有差异以官方仓库 README 为准但“数据要持久化、遥测可关闭”这两个思路是通用的。2.3 启动、初始化和访问配置配置文件准备好后在 compose 文件所在目录执行docker compose pull docker compose up -dpull会先拉取镜像up -d则是以后台模式创建并启动容器。第一次启动需要初始化数据库结构通常要等 10 到 40 秒取决于机器性能和磁盘速度。可以用下面的命令实时盯日志docker logs -f affine看到类似Listening on host 0.0.0.0 port 3010或“started”字样说明服务起来了。然后浏览器访问http://你的服务器IP:3010注册第一个管理员账号。这个账号很关键它不仅是你的工作区账号在后续升级和权限管理里也有特殊地位。接下来我强烈建议做两件事一是设置 HTTPS 反向代理而不是直接用 IP 端口访问二是进设置里关掉不必要的统计上报。AFFiNE 本身支持通过环境变量关闭遥测但界面里有时还会有前端上报项顺手关掉更干净。反向代理我用的是 Caddy因为它会自动申请和续期证书配置也极其简单。在 Caddyfile 里写上note.example.com { reverse_proxy 127.0.0.1:3010 }然后重启 Caddy 即可。如果你用 Nginx对应的转发配置也不复杂但要注意代理长连接超时时间不能设太短否则白板协作和大数据量载入可能被切断。3. 部署后的核心配置与性能调优容器起来只是第一步真正让 AFFiNE 适合长期使用的是部署之后的一系列选择底层存储怎么设计、备份怎么做、资源占用怎么控制。这几个点从 Notion 迁移过来的用户经常忽略等数据量大了再改就很痛苦。3.1 产品里的“数据库”和底层数据库是两回事很多新手第一次听到 AFFiNE 有“数据库”功能以为部署的时候必须先装一个数据库软件这是一个非常普遍的误解。AFFiNE 产品层面的 database block是你编辑内容时直接插入的一个块它自带表格、看板、日历等交互视图不需要你在系统里为它安装任何额外的数据库。也就是说你随时可以在文档里建一个“书名管理表”或“任务清单”数据由 AFFiNE 统一存储你不需要知道它存在哪里。而 AFFiNE 服务自身在底层存储业务数据时可以用 SQLite、PostgreSQL 等数据库。默认情况下单机自托管用内置的 SQLite 文件就够镜像数据卷里那个.affine相关文件就是数据库本体。只有当你有多实例、高并发、需要在线协作大量用户同时读写时才建议把底层存储切到 PostgreSQL。我个人的建议是个人使用、三五个家人朋友用默认 SQLite 完全没问题少一个依赖就少一个故障点如果是团队协作、并发高、数据量上百万级再考虑外接 PostgreSQL。切换底层数据库意味着重新初始化数据不是改个配置文件就行的操作前期别轻易上生产级重装备。3.2 数据卷、备份方案和升级策略自托管最怕丢数据。AFFiNE 的数据在宿主机上有两个关键位置一个是映射出来的数据卷比如我们前面配置的./affine_data存放了数据库文件、附件和配置文件另一个如果接了外部对象存储附件还可能存在 MinIO、S3 这些服务里。我的备份策略很简单每天凌晨用 rsync 把整个affine_data目录同步到另一块磁盘每周再打包一次压缩后传到对象存储。不需要什么高深工具crontab 加一条命令就行0 3 * * * rsync -a --delete /opt/affine/affine_data/ /backup/affine_data/如果是需要 PostgreSQL 的场景备份就得用pg_dump导出结构加数据。更讲究的话可以在升级前先停容器再整体备份目录这样数据文件处于一致状态不会出现写到一半的脏页。升级这个操作我踩过一次坑。那次我直接改了镜像 tag 然后docker compose up -d结果新版本初始化脚本跑了一半失败容器反复重启。最后靠升级前留下的备份恢复到前一版本才救回来。现在我的原则是任何升级前必先备份升级后先看日志确认健康再逐步验证核心功能千万不能“无事发生”式地关掉终端。3.3 资源占用与访问速度优化AFFiNE 的资源占用不算夸张。一个空工作区加两三个页面空闲时内存大概在 800MB 到 1.2GB 之间打开带有大图片或复杂白板文件的页面时内存会短暂冲到 2GB 以上。所以 2G 内存能跑3G 以上才舒服。访问速度上影响最大的其实是静态资源加载而不是服务器本身。AFFiNE 的前端是纯静态页面如果直接用容器默认端口访问下载首页 JS/CSS 时没有任何压缩带宽小会很慢。我部署后做了两件事一是在 Nginx/Caddy 层的反代配置里开启 gzip二是给静态资源加长缓存时间。这两步做完体感负荷下降了一个档尤其人在国内服务器访问时差异特别明显。如果你的 VPS 带宽很紧张还有一个偏方把静态资源放到 CDN 上。但这需要前端构建时修改资源路径操作成本高一般人没必要。日常用 gzip 浏览器缓存已经能应付绝大多数情况。4. 从 Notion 迁移到 AFFiNE 的实操经验部署只是开始真正费时间的是数据迁移。我从 Notion 搬迁了三百多个页面、二十多个数据库进来前后花了大概一个晚上。这个过程中最大的教训是不要指望一键迁移能完美复制一切。把你需要的挑出来重新组织速度和效果反而更好。4.1 文档迁移Markdown 导入最常见AFFiNE 支持导入 Markdown、HTML、纯文本等格式所以最稳妥的迁移链路是从 Notion 导出 Markdown/CSV再在 AFFiNE 里导入。Notion 的导出入口在 Settings 里的 Export workspace可以选择导出格式为 Markdown CSV。导出的 zip 包里每个页面是一个.md文件图片则在单独目录里。然后到 AFFiNE 的对应工作区选择导入文件夹或文件把整包解压后的 Markdown 文件拉进去。实际导入后你会发现问题Notion 里的嵌套子页面在 Markdown 导出时会被压成相对链接AFFiNE 导入后未必能精确还原成父子页面关系数据库里的富文本内容更是不可能 100% 重建。我的处理办法是分两类走——纯文档页面直接导入复杂数据库页面先导出 CSV 再手工建立数据库块批量导入。对于图片导入后建议在 AFFiNE 里重建附件存储而不是依赖原始链接避免 Notion 图床地址失效。4.2 工作区结构怎么调整Notion 的典型结构是“Workspace - Page - 子 Page”的树状层级很多人习惯用目录折叠来组织一切。AFFiNE 虽然也支持类似的层级但它的白板能力天然鼓励你用更“网状”的方式组织信息。我刚迁移时犯了个错误把 Notion 那套“每层一个目录页 下面全是子页面”的结构照搬过来结果打开工作区像看一棵没有尽头的树白板的意义完全没体现。后来我做了一次重建文档类内容读书笔记、周报、会议记录按文件夹归档少交叉嵌套项目类和知识类内容则在白板里画地图把关键页面作为卡片连接起来。这么调整后工作区和 Notion 的区别一下子就出来了。以前找一份半年后的资料我得顺着目录一级级点下去现在打开项目白板那个文档处在流程图的哪个位置一眼就能定位。AFFiNE 的“双链”能力虽然已经有了但我个人的经验是不要把它当 Obsidian 用——它是靠“页面依赖 画布可视化”来管理信息的思维方式要跟着变。4.3 白板场景替代 Notion FigJam/Miro以前我在 Notion 里只能记录文字结构画流程得再开一个 FigJam 或 Miro然后贴链接回来信息被割裂成两半。AFFiNE 最让我爽的就是这个场景被消灭了。比如整理一个“个人知识体系”我直接打开一张空白白板把核心方法论当成卡片拖在中央每个方法论扯一个分支分支上放解释笔记再拉一个“学习计划数据库”的块放到右下角。数据库里的任务卡片能直接跟白板上的节点连线整体看就是一个活的系统而不是一份静态目录。白板本身的操作也很顺手支持框选、拖拽、缩放可以自由手写批注还支持画笔加便签。做产品原型、技术架构图、阅读地图都没问题。它不可能替代专业绘图工具的全部功能但在“把文档和可视化放同一个文件里”这件事上比“Notion 外部白板工具”的组合顺手得多。5. 常见问题与排查技巧实录自托管和商业软件最大的差别是出了问题没人替你背锅一切靠日志和排查。我部署和后续维护 AFFiNE 这段时间遇到过几次比较典型的故障写在这里供你参考。5.1 容器起不来端口冲突、内存不够、镜像拉取失败这类问题最常见也最好排查。第一步永远是看日志docker logs --tail 100 affine如果日志里提示端口地址占用说明 3010 端口被其他进程占了修改宿主机的映射端口就行。如果是启动后几秒就死掉加restart: unless-stopped的话容器会反复重启日志里一般会留下内存不足、数据库锁文件之类的关键字。我曾经在一台 1G 内存的机器上试跑AFFiNE 刚启动就被 OOM Killer 杀掉加了个 swap 分区后勉强能跑但体验很差。建议内存不足就升级配置别硬撑。镜像拉取失败或者慢最典型的是 ghcr.io 连不上。前面说过配镜像加速器是正解。如果已经配置了加速器还是失败可以检查 Docker daemon 是否真的重启生效了用docker info查看 Registry Mirrors 列表。5.2 图片或附件上传失败数据卷权限和对象存储没配对AFFiNE 上传附件时如果提示保存失败或刷新后图片消失大概率不是软件问题而是数据卷映射或权限问题。容器内进程需要能写/app/data目录宿主机对应目录如果权限是 root 所有容器内非 root 用户写不进去就会静默失败或报错。解决方法是确保宿主机目录属主与容器内运行用户匹配或者干脆把目录权限改成 777 来快速验证正式环境不建议。如果是配置了 S3 或 MinIO 做对象存储还要检查桶名、区域、密钥是否正确尤其是自定义域名访问时S3 endpoint 要写对。5.3 升级后无法登录或数据异常备份是第一道防线我遇过升级后账号登不进去的情况当时第一反应是密码错了连续试了几次才发现是升级迁移脚本更新了用户表结构老会话失效了。这时候最安全的做法不是改数据库而是检查官方 issue 有没有对应迁移的说明同时回滚到备份。没有备份的情况下先不要急着删容器。把数据卷目录完整复制一份出来只读分析。AFFiNE 的数据主要存在底层数据库文件中用 SQLite 浏览器打开看表结构是否正常。老实说这类问题能靠“重新注册账号”解决的都算轻的真遇到数据表不匹配还得靠专业手段。5.4 常见问题速查表症状可能原因解决方式容器启动后马上退出端口冲突 / 内存不足改端口映射加内存或 swap页面样式加载很慢静态资源未压缩 / 带宽不足反向代理开 gzip加缓存头图片上传后丢失数据卷未映射 / 权限错误检查数据卷目录存在和写权限登录后显示空白页前端版本和后端版本不匹配固定镜像 tag同时升级前后端数据库功能无法筛选数据库视图字段类型混用重建属性列确认单选/多选类型一致白板连线错位网络延迟 / WebSocket 断开检查反代 WebSocket 超时设置这张表是我遇到的高频问题不一定覆盖所有情况但覆盖了自托管新手最容易踩的 90%。排查时记住一个顺序先日志、后配置、再数据不要上来就动数据库。我在实际操作中最深的体会是AFFiNE 作为“Notion 替代品”这个定位目前更适合对数据主权有要求的个人用户和中小团队。它的文档编辑和白板融合体验已经超过我的预期数据库功能覆盖日常绰绰有余但有些细节——比如导入复杂 Notion 页面的还原度、移动端编辑手感、插件生态——跟 Notion 这种打磨多年的商业产品相比还有差距。你不能指望它完美复刻 Notion比如 Notion AI 或大量第三方集成目前就是它的弱项。不过我自己已经不太需要那些花哨功能了。我需要的是一个能快速记录、自由梳理、数据握在手里的工具。AFFiNE 用 Docker 跑起来以后我真正感受到的是一种“安全感”——服务器是我自己的备份是我定的升级是我决定的。这份可控性是我用 Notion 这么多年从来没有过的。最后再分享一个小技巧部署完成后把数据卷目录也同步到你常用的加密网盘或移动硬盘里。别问问就是防“单点故障”。