写作时我想保持真实从业者口吻避免AI套路。我以自己长期折腾知识管理工具、最终被AFFiNE吸引的角度切入。正文会贯穿“为什么选它”“怎么用起来”“怎么自己部署”“遇到坑怎么办”这条线索最后自然收尾。我现在按这个思路开始全文写作。 这两年知识管理工具圈最不缺的就是新产品但真正让我愿意长期用下来的不多。AFFiNE是其中一个。第一次看到它的时候我心里想的是“又来了一个本地优先的Notion替代品。”结果用了一个月之后我把主力知识库从原来的Markdown文件夹体系整个迁了过来。原因不是它某个单点功能有多惊艳而是它把“编辑体验、结构化数据、自由度”这三件事捏合得足够顺滑刚好卡在一个很舒适的平衡点上。AFFiNE的官方定位是“新一代开源知识生产平台”关键词拆开看就是开源、知识生产、平台。但如果你只用“开源Notion”去理解它会错过很多设计上的想法。它默认支持Markdown语法、双向链接、块级编辑、看板数据库、无限画布白板再加上端到端加密和自托管部署能力既照顾了喜欢自由书写的用户也照顾了要把信息结构化、协作化的团队场景。这篇文章我会完整拆一遍它的核心设计好在哪、日常怎么用顺手、自己部署要注意什么、以及实际踩过的坑。无论你是个人知识库重度用户还是想帮团队找一个私有化方案应该都能从中拿到点实在的东西。1. AFFiNE的核心设计为什么值得重新认识一次1.1 从“本地优先”到“协作优先”它没有站错队AFFiNE底层是本地优先local-first架构文档数据默认存在本地同时提供了可选的云端同步和自托管方案。这一点和纯云端的Notion有本质区别。我的理解是它默认把数据主权交还给用户再用同步层把协作能力补上。对个人用户来说文件在你硬盘上永远不用担心服务商哪天调整定价或者关闭服务对团队来说数据能落进自己的服务器合规压力会小很多。这个架构带来的一个实际好处是启动速度快离线可写。我经常在高铁上打开AFFiNE接着写昨天的技术复盘没有网络也完全不影响输入体验。等回到有网环境改动会自动合并同步。这种体验和当年用本地Markdown文件夹写笔记很接近但多了一层数据库和协同能力。不过要注意本地优先不等于“自动备份”。本地数据只是存在本地不等于多副本容灾。如果你没有配置同步或定期备份硬盘坏了一样丢数据。这也是后面部署章节里我会反复强调备份的原因。1.2 数据库驱动的内容组织文档和表格原本就是同一件事AFFiNE的另一个核心设计是用数据库来组织内容。你可以把一整个页面想象成一张表每一条记录record就是一个页面字段property就是页面的属性。这个思路和Notion的database很相似但AFFiNE把它做得更轻。举个例子我维护了一个“读书笔记”页面里面每一行是一本书字段有书名、作者、状态在读/读完/想读、评分、标签。点开某一行就进入这本书独立的文档页可以写长文笔记。这个结构天然适合构建知识库既保留了数据库的筛选能力又保留了自由写作的空间。同样是这个数据库模型AFFiNE支持给字段选类型文本、数字、日期、复选框、标签、链接等。这种“结构化程度按需调整”的思路我觉得比一上来就逼你用复杂模板的工具要友好得多。1.3 无限白板的边界和适用场景AFFiNE内置了无限画布白板whiteboard可以插入便签、图形、连线、文本块还能和文档块互相转换。很多人把它当成Miro或FigJam的替代品。我个人用得最多的地方是两类场景一类是画架构图比如把服务模块、数据流画出来另一类是头脑风暴把一个方向拆成若干子问题贴到画布上再用连线梳理依赖。不过我不建议把白板当成日常笔记主界面。白板适合表达“关系”和“空间位置”而长文写作、知识积累还是更适合普通文档布局。AFFiNE的聪明之处在于它允许你在两种形态之间切换同一块内容既可以用文档方式阅读也可以变成白板里的卡片。这个自由度很有价值但对新手来说也可能造成选择困难。我的建议是初期先专注用文档和数据库白板留到确实需要梳理复杂关系时再上。2. 核心功能拆解与实操要点2.1 编辑器块级编辑的效率和边界AFFiNE的文档基于块block模型。按回车新建段落、输入“/”唤起菜单插入不同类型的块这套交互对用过Notion的人几乎零学习成本。它还保留了很纯正的Markdown输入体验比如输入“#”加空格变成一级标题输入“-”加空格变成列表项输入“”变成引用块。对写惯了Markdown的人来说这种“写得快、不用离开键盘”的体验非常加分。块的类型覆盖了日常绝大多数场景文本、标题、列表、待办事项、引用、代码块、数学公式、图片、文件附件、表格、内嵌链接等。尤其值得说的是代码块支持常见编程语言高亮写技术文档时直接内嵌代码片段非常方便。实操层面有几个值得养成的习惯块引用block reference可以用来把某段内容嵌入到另一个页面适合“一处维护、多处引用”的场景。键入“/t”可以快速新建表格适合在文档里做轻量对照。图片文件直接拖入文档即可AFFiNE会把文件导入到当前工作区对应的存储里注意如果只存在本地又没备份图片丢失风险高于纯文本内容。2.2 双向链接与知识图谱让积累变成网络AFFiNE支持双向链接bidirectional link也就是你可以用“[[页面名]]”的语法在任意文档里链接到另一篇文档。系统会自动在目标页面底部显示“被哪些页面引用”还能生成全局关系图谱。这个机制把我从文件夹树中解放出来。以前我维护技术笔记习惯按“Docker/网络/数据库”这种层级建目录一个主题只能放在一个位置。现在更自然的做法是写成一篇独立页面然后通过链接把它挂到多个父级入口。比如一篇“基于Docker部署PostgreSQL”的笔记既会被“Docker实操”引用也会被“数据库部署”引用还能链接到“备份策略”这类关联文档。双向链接的关键用法是“多入口导航”让同一篇文档通过不同路径被发现而不是强迫你提前规划好一个完美目录。知识图谱则用来观察内容之间的连接密度如果某个页面周围没有任何链接说明它可能是一篇孤岛文档可以考虑主动补充关联。不过我不建议过度追求图谱形状知识管理的目标是“用的时候找得到”不是“图谱好看”。2.3 数据库、看板与筛选适合轻量项目管理AFFiNE的数据库视图支持表格table、看板kanban、画廊gallery等。我团队内部布置任务经常用看板视图来管理把字段“状态”设为“待办/进行中/已完成/阻塞”看板上自然分成几列拖拽卡片即可变更状态。这个功能替代了一部分轻量项目管理工具。和Jira、Trello比它的优势是“和文档纯天然联动”一个任务卡片点进去可以写很长的细节文档、贴链接、传附件不需要额外再跳一个工具。做小型项目、内容策划、技术方案推进完全够用。筛选和排序能力也很扎实。比如我有个“内容选题库”每篇文章有字段“状态草稿/写作中/已发布”“平台”“标签”“计划日期”。用表格视图可以按字段筛选快速找到所有“已发布且带Docker标签”的文章这是普通文件夹笔记做不到的。2.4 权限、协作与发布单人工作流之外的价值AFFiNE对多成员协作也有完整支持工作区workspace可以邀请多人成员可以按角色配置只读、评论、编辑等权限。在团队场景下页面级别的共享链接可以直接发给未登录用户适合对外分享方案文档。发布功能对写公开博客的人来说很实用。AFFiNE支持将公开页面释放为一个可访问的网页链接不需要部署额外的博客系统。生成的页面保持排版样式简洁适合技术文档、产品说明、周报展示这类场景。需要注意的一点是协作模式下“冲突解决”依赖后端同步机制。如果你自托管这部分稳定性取决于服务器和网络环境。我自己用Docker部署的实例多人同时编辑长文档时偶有同步延迟但从未发生过严重覆盖事件。如果你要支撑十几人以上同时高频编辑建议提前压测不要等到上线再验证。3. 自托管部署从Docker到日常运维3.1 为什么默认推荐Docker Compose部署AFFiNE分为云端版AFFiNE Cloud和自托管版deployment版。自托管版需要自己部署最省心的路径就是用Docker Compose。官方仓库提供了一份完整的compose文件里面包含了四个核心服务app前端API、databasePostgreSQL、object-storageMinIO用来存图片附件、cacheRedis用来做会话与队列缓存。这种多服务架构拆得很清晰但给第一次部署的人会带来一点压力。我的建议是先完整理解各组件职责再动手部署不要盲目复制命令。否则出了问题你连日志里报错的组件是干什么的都不知道。资源方面官方建议至少2核CPU和4GB内存。我自己在2核4G的VPS上跑轻量使用没问题但如果多人并发、频繁上传大图内存会吃紧建议条件允许的话升到8G或者限制Docker内存上限。3.2 部署步骤与关键配置先说结论如果你只是想试一下最快的方式是git clone https://github.com/toeverything/AFFiNE.git cd AFFiNE docker compose up -d但这套默认配置只能本机访问不能直接上生产。实战中我按下面几步做了加固第一步创建独立的部署目录并且拉取稳定的release标签而不是main分支。mkdir /opt/affine cd /opt/affine第二步准备环境变量文件。AFFiNE的compose配置里很多参数可以通过环境变量覆盖重点关注这几个AFFINE_SERVER_PORT服务监听端口默认8080。AFFINE_DATABASE_URLPostgreSQL连接串。AFFINE_OBJECT_STORAGE_*MinIO存储配置。AFFINE_JWT_SECRETJWT签名密钥务必改成足够随机的字符串。AFFINE_ACCESS_TOKEN_EXPIRATION登录有效期控制。其中JWT密钥是安全关键项。默认值如果被猜到攻击者理论上可以伪造登录态。我用OpenSSL生成了一串随机值openssl rand -hex 32把输出填到环境变量里。PostgreSQL和MinIO的密码同理全部改成独立随机密码。第三步配置反向代理和HTTPS。由于AFFiNE前后端混合WebSocket协议也要支持。我用Nginx做了一层反向代理核心配置只有几个要点代理到容器的8080端口、开启WebSocket升级、强制HTTPS跳转。如果涉及大文件上传还需要调大client_max_body_size否则上传图片会报413错误。注意自托管后默认不启用AFFiNE Cloud的同步和中继能力。多人协作如果不在同一局域网你需要自己解决公网可达、HTTPS证书、WebSocket代理等问题。这一步是自托管和开箱即用之间的真实成本提前评估好再投入。3.3 数据备份与恢复自托管最不能省略的环节自托管AFFiNE数据存在三个地方PostgreSQL里的文档结构、MinIO里的图片和附件、Redis里的缓存和会话。真正需要认真备份的是前两者Redis崩了重建问题不大。我使用crontab做每日备份备份脚本分三步用pg_dump导出PostgreSQL所有数据库。用s3cmd或MinIO Client同步object-storage目录到备份盘。将两个备份文件打包加密传到异地存储。恢复的时候反向操作即可先恢复PostgreSQL数据再恢复MinIO对象存储最后重启整个AFFiNE容器栈。需要注意PostgreSQL版本和MinIO版本要尽量与备份时一致跨大版本恢复容易出现兼容性问题。这一点比配置本身更容易被忽略建议备份时顺带记录当时的镜像版本号。3.4 版本升级的稳妥套路AFFiNE迭代速度很快新版本常常带来编辑器和协同体验的改进。但升级有风险不要直接在主力环境上“上去就是最新”。我的升级流程是这样的读升级说明重点关注破坏性变更。在测试环境先执行一次完整升级确认数据迁移没问题。对生产环境打快照或完整备份。拉取新镜像docker compose up -d。观察日志跑冒烟测试确认关键功能正常。这台机器上我经历过几次升级最大的一次障碍是数据库迁移脚本执行时间过长因为文档数据量已经不小。解决方案是避峰操作提前停服给迁移预留足够时间。普通用户如果数据量不大其实升级很顺滑但我还是不建议跳过测试环境这步尤其当你有长期历史数据时。4. 常见问题与排查技巧实录4.1 白板内容消失或不同步白板内容比普通文档复杂涉及坐标、连线、内嵌块等数据。如果你发现自己画的内容在不同设备上不一致多半是同步冲突或白板数据更新频率高但同步策略滞后导致的。我遇到过的典型场景是在公司电脑上画架构图回家打开同一工作区看到的是旧版本。排查后发现自托管实例的WebSocket连接不够稳定客户端没有实时收到远端变更。解决办法是刷新页面或者检查Nginx是否配置了正确的WebSocket升级头。如果频繁出现检查客户端与服务器之间的网络稳定性以及在自托管节点上确认Redis运行正常。4.2 图片上传413错误这是Nginx反代没调大请求体限制的典型表现。解决办法是在Nginx配置文件里加上client_max_body_size 50m;如果还是报错看AFFiNE容器日志确认MinIO是否正常写入。我遇到过MinIO磁盘满导致上传失败的情况日志里直接报“unable to store object”。这个排查起来不难但也说明查看容器日志的习惯很重要docker compose logs -f app docker compose logs -f object-storage4.3 编辑器卡顿和输入延迟很多人自托管后会遇到页面操作不跟手的情况。首先要排查服务器负载AFFiNE对内存比较敏感如果你开了很多工作区内存不足会引起GC频繁、响应变慢。其次浏览器端缓存也会影响体验锁屏状态下或者长时间开着不关内存占用会上升。经验做法是把数据库和缓存服务单独放一个节点应用服务放另一个节点减少互相影响。但如果你只是中小规模使用一台配置好些的主机就够了。我自己的2C4G轻量服务器其实够用只有一次因为没限制Docker日志大小磁盘被日志撑满导致服务假死。提前配置日志轮转是个非常必要的习惯。4.4 外部登录和OAuth配置踩坑AFFiNE支持OAuth登录如GitHub、Google。配置时最容易犯的错是回调地址填错。GitHub OAuth应用填回调URL时必须和你的外部访问域名完全一致包括结尾路径。如果有反代、HTTPS、端口映射任何一个环节不一致都会导致登录失败。如果不想折腾私钥和OAuth可以先只用邮箱密码登录。自托管默认支持邮箱注册登录配合JWT密钥安全性足够日常使用。等团队规模大了再接入SSO也不迟。5. 对开源生态的一点个人判断AFFiNE之所以能在短时间内获得关注除了产品本身好用开源社区的氛围也功不可没。它的代码仓库公开Issue讨论活跃每个版本发布都有详细的变更说明对开发者很友好。如果你感兴趣可以从它的前端技术栈入手了解一个复杂块编辑器和白板是如何协同工作的这种“活项目”比零散教程更有价值。对我个人而言最看重的是它没有把自己锁死在单一商业模式上。用户既可以买云服务省心使用也可以自托管拥抱完全自主控制权。这种双轨模式在知识工具领域并不多见。当然这也意味着你选择自托管就要自己承担运维成本没有什么方案是零代价的。如果你是一个习惯用“工具越简单越好”的极简派AFFiNE可能会让你觉得功能过于丰富。但如果你需要的是一个既能随手记录、又能结构化整理、还能私有化部署的知识生产平台它值得你花一个周末去尝试。最初那一个月我一边迁移数据一边调整笔记结构确实花了不少时间但现在回头看这个时间投入是值得的。知识管理这件事工具顺手了积累才能真正长出来。