AFFiNE 0.27.4 介绍与选型指南

AFFiNE 0.27.4 产品定位、技术架构、功能特性与自托管要求全解析，含与 Notion/Outline/Excalidraw/Onyx 的量化选型对比（Stars/许可/版本/部署形态），全部外部数据 2026-10-25 实地查询，部署与功能基于官方 Docker Compose 实测。

AFFiNEAFFiNE自托管2026/10/25

AFFiNE 0.27.4 介绍与选型指南

目标：讲清 AFFiNE 的产品定位、技术架构、核心功能与自托管要求，给出与 Notion、Outline、Excalidraw、Onyx 的量化选型对比，帮助判断「什么团队适合选 AFFiNE」。本文全部外部数据（版本、Stars、许可证）于 2026-10-25 从官方源实地查询，部署与功能描述基于 2026-10-25 在一台 Ubuntu 服务器上以官方 Docker Compose 结构实测 AFFiNE 0.27.4 的结果。

一、环境信息

项目值
调研与实测日期2026-10-25
实测服务器Ubuntu Linux（内核 6.x，x86_64），内网 IP 192.168.146.128
Docker / ComposeDocker 29.9.2 / Docker Compose v5.6.1
AFFiNE 版本0.27.4（GitHub Releases 标记 Latest 的稳定 tag v0.27.4；官方服务端镜像 ghcr.io/toeverything/affine:0.27.4）
依赖组件PostgreSQL 16（pgvector/pgvector:pg16）、Redis 7（redis:7）
部署形态官方 Docker Compose（allinone 单应用 + 迁移任务 + PostgreSQL + Redis）
实测验证管理员初始化、工作区创建、Blob 上传落盘、GraphQL API 探活、整栈重启后数据持久化，全部通过

二、软件概述

AFFiNE 是一款开源、可自托管、本地优先（Local-First）、隐私至上的「全能工作区」，把文档与白板超融合在同一个编辑画布中，官方口号是 "There can be more than Notion and Miro"——即同时对标 Notion（结构化文档/知识库）与 Miro（白板协作）。

  • 开发方：TOEVERYTHING PTE. LTD.（2022 年至今持续开发）。
  • 技术栈：TypeScript 全栈；服务端 Node.js + NestJS + GraphQL；前端 React；编辑器为团队自研的 BlockSuite；多端同步基于 CRDT（Yjs）。
  • 开源许可（2026-10-25 核实）：主仓库绝大部分内容 MIT；packages/backend 与 packages/common/native 目录采用 AFFiNE Enterprise Edition（EE）许可，自托管核心功能免费，团队配额等商业特性需购买许可。
  • 社区规模（2026-10-25 查询）：GitHub Stars 约 74k，Releases 保持高频滚动（stable / beta / canary 三通道并行）。

💡 技术拓展：「本地优先（Local-First）」不止一种实现路线。常见形态对比：

形态原理/特点适用场景/取舍
纯云端（Cloud-only）数据只存服务端，离线不可用Notion 为代表；协作最强，离线最弱
本地优先 + CRDT 同步数据先落本地，后台经 CRDT 合并到多端AFFiNE 采用（Yjs）；离线可用、冲突自动合并，实现复杂度高
本地文件 + 手动同步数据是本地文件，靠网盘/Git 同步Obsidian 为代表；简单透明，实时协作弱

AFFiNE 选择「本地优先 + CRDT」，因此同时具备离线可用与实时协作能力，代价是服务端需要维护文档快照合并（大文档合并是主要内存消耗点，见六章）。

三、核心架构

AFFiNE 自托管侧为「一体应用 + 两类基础设施」的结构（0.27.4 官方 Compose 实测）：

组件角色说明
AFFiNE Server（allinone）Web 前端 + NestJS 服务端 + GraphQL API（/graphql）+ WebSocket 同步 + 管理面板（/admin）官方单镜像 ghcr.io/toeverything/affine，内含一个一次性迁移服务（启动时执行 self-host-predeploy.js 完成数据库迁移与密钥生成）
PostgreSQL 16（pgvector）主数据库用户、工作区、文档快照、权限、配置等全部结构化数据；pgvector 扩展支撑 AI 向量能力
Redis 7缓存 + 后台任务队列 + 同步基础设施官方要求 Redis 6.x/7.x，AFFiNE 无法脱离 Redis 运行
Blob 存储上传文件（图片、附件、头像）默认本地文件系统（./data/storage），可切换 S3 兼容对象存储 / Cloudflare R2

关键架构事实（均有实测或官方文档佐证）：

  1. 文档数据进数据库，文件数据进 Blob 存储。文档正文以 CRDT 快照形式存于 PostgreSQL；上传的图片/附件落在 ./data/storage。本文实测上传头像后，文件出现在 data/storage/avatars/ 目录（含同名 .metadata.json）。
  2. 配置体系在 0.27 发生重大调整：应用配置以 config/config.json 为首选来源（官方原话：环境变量不再是首选配置源，仅保留用于服务接线与兼容别名）；管理面板（Admin Panel）保存的设置入库。0.27 之前的 .env 部署需按官方迁移清单过渡。
  3. 客户端/服务端兼容矩阵：0.27 系服务端仅支持 0.26 及以上版本客户端连接（0.27 Release Notes 明确的 Breaking Change）。
  4. 首次启动自动初始化：迁移服务自动生成并持久化 config/private.key（实测确认），该私钥用于签名/加密，丢失或替换会导致已加密数据失效。

四、功能特性

基于 0.27.4 实测与官方文档整理：

  • 文档与白板超融合：同一页面可在「文档模式（Doc）」与「白板模式（Edgeless）」间一键切换；白板支持图形、便签、连接线、画笔、演示等。
  • 块编辑器：BlockSuite 提供段落、标题、列表、代码块、数据库视图（表格/看板）、嵌入、附件等块类型。
  • 知识管理：日记（Journal）、双向链接、标签、收藏、全文检索（可外接 Elasticsearch/Manticore 索引器）。
  • 实时协作：基于 Yjs 的多人光标与冲突合并；支持评论、提及、通知。
  • AI 能力（Copilot）：支持 BYOK（自带 API Key），可接 OpenAI（GPT 系列）、Google Gemini、Anthropic Claude 等，0.27 系新增 byok 自定义端点；另有 Exa 搜索、Unsplash 配图集成。
  • 多端覆盖：Web、桌面客户端（Windows/macOS/Linux）、移动端 App；桌面端可直连自托管实例。
  • 自托管管理：/admin 管理面板（用户/工作区/队列/设置）、用户导入、密码重置、封禁、OAuth 2.0（Google/GitHub/OIDC/Apple）、SMTP 邮件、存储配额、团队许可（Team License）、Prometheus 监控。
  • 开放接口：全量 GraphQL API（实测开启 introspection，可无鉴权查询 serverConfig.version 等公共信息），支持 MCP 凭证（createMcpCredential）。

五、快速开始（最小可用示例）

以下步骤在 2026-10-25 实测通过，是官方推荐路径的最小闭环（完整部署细节与排障见《AFFiNE 0.27.4 Docker Compose 部署指南》）：

# 1. 建部署目录并下载官方 Compose 文件（随每个稳定版 Release 发布）
mkdir -p /opt/data/quzuo/tmp/affine/deploy && cd /opt/data/quzuo/tmp/affine/deploy
mkdir -p config data
curl -L -o docker-compose.yml https://github.com/toeverything/AFFiNE/releases/latest/download/docker-compose.yml

# 2. 创建应用配置 config/config.json（0.27 起不再需要 .env）
curl -L -o config/config.json https://github.com/toeverything/AFFiNE/releases/latest/download/config.json.example
# 按需修改 server.externalUrl 为最终访问地址，例如 http://192.168.146.128:8137

# 3. 启动
docker compose up -d
docker compose ps

实测启动后服务状态（本文实验将宿主端口调整为 8137、并为 PostgreSQL 设置口令，详见部署指南）：

NAME                     IMAGE                                STATUS                   PORTS
affine-0.27.4-postgres   pgvector/pgvector:pg16               Up 15 seconds (healthy)  5432/tcp
affine-0.27.4-redis      redis:7                              Up 15 seconds (healthy)  6379/tcp
affine-0.27.4-server     ghcr.io/toeverything/affine:0.27.4   Up                       0.0.0.0:8137->3010/tcp

⚠️ 注意：首次访问 http://<服务器>:8137/ 会 302 跳转到 /admin/setup，需在向导中创建第一个管理员账号（本文示例：admin@example.com / q1w2e3r4），创建完成前普通首页不可用。

探活验证（无需登录）：

curl -s http://192.168.146.128:8137/info

实测回显：

{"compatibility":"0.27.4","message":"AFFiNE 0.27.4 Server","type":"selfhosted","flavor":"allinone"}

六、适用场景与限制

适用场景：

  1. 隐私敏感团队/个人：要求数据完全落在自己的服务器与磁盘上（文档进 PostgreSQL、文件进本地 Blob 目录）。
  2. 既要结构化文档又要自由白板的创作型团队：AFFiNE 是少数把两类画布原生融合的开源产品。
  3. 离线优先工作流：本地优先架构保证弱网/离线可用，恢复后自动同步合并。
  4. 需要 AI 但不愿把数据交给第三方：BYOK 模式下用自有 API Key 调用模型。

限制与边界（实测与官方文档确认）：

  • 数据库唯一：服务端仅支持 PostgreSQL（且 AI 全量能力需要 pgvector 扩展），不支持 MySQL/SQLite。
  • Redis 为硬依赖：无 Redis 无法运行；默认占用 0–4 共 5 个逻辑库。
  • 内存敏感：官方实测「合并一份累计 1 万次修改的文档，峰值内存约 1 GB」；官方建议基础 2 GB RAM，有大文档（>1 万词）建议 4 GB；基础硬件门槛 4 核 CPU。
  • 版本升级有断代：0.27 起环境变量配置迁移至 config.json（Breaking Change）；0.27 服务端拒绝 0.26 以下客户端。
  • 商业特性边界：团队席位/配额、部分企业能力受 EE 许可约束，需购买 Team License。
  • 资源基线：服务端安装本身约需 1.5 GB 磁盘；官方观测数据为每 1 千篇文档 PostgreSQL 增长约 100 MB、每 1 千个 Blob 增长约 10 GB。

七、同类选型对比

以下量化数据均为 2026-10-25 从各官方仓库/官网实地查询：

维度AFFiNENotionOutlineExcalidrawOnyx
产品定位文档+白板融合的全能工作区云端全能工作区 SaaS团队知识库 Wiki手绘风虚拟白板AI 企业搜索/问答助手
开源许可MIT + 后端 EE 双许可专有（闭源）BSL 1.1（源码可用、商用受限）MITMIT + ee 目录企业许可
GitHub Stars≈74k不适用≈41k≈135k≈33k
最新版本（2026-10-25）v0.27.4（stable）SaaS 滚动更新v1.12.0v0.18.1v5.0.0
自托管✅ 官方 Compose（PostgreSQL+Redis）❌ 仅官方云✅（PostgreSQL+Redis+对象存储）✅（白板组件/简易后端）✅（PostgreSQL+Redis+模型服务）
本地优先/离线✅ CRDT 本地优先⚠️ 有限离线缓存❌ 云端优先✅ 纯前端可离线❌
原生白板✅（与文档同画布）❌❌✅（仅此一项）❌
AI 能力Copilot，BYOK 自带 KeyNotion AI（订阅）第三方集成图生代码等插件核心即 AI 问答（多模型）
客户端兼容约束0.27 服务端需 ≥0.26 客户端由厂商托管浏览器/桌面浏览器浏览器
商业模式开源 + 云服务 + Team License订阅制 SaaS开源 + 云服务开源 + Plus 订阅开源 + 云服务

「如果…则…」选型建议：

  • 如果必须数据自主 + 同时要文档和白板 → 选 AFFiNE（开源世界里该组合的完成度最高）。
  • 如果不想运维任何基础设施、接受订阅费 → Notion（省心但数据在厂商云上）。
  • 如果只要规范化团队 Wiki、不要白板 → Outline（注意其 BSL 1.1 许可对商用分发的限制）。
  • 如果只要一块嵌入式的手绘白板 → Excalidraw（轻量、可嵌入自家产品，AFFiNE 白板同属此类体验的融合实现）。
  • 如果核心诉求是跨系统的 AI 知识问答而非文档创作 → Onyx。

八、参考链接