AFFiNE 详细部署教程：自托管 Notion + Miro 融合工作区 | 极客的赛博空间

AFFiNE 是一个开源、隐私优先的下一代知识库，融合了文档（Docs）、画布（Whiteboard）和表格（Tables）的功能，可作为 Notion 和 Miro 的自托管替代品。本教程将指导你使用官方推荐的 Docker Compose 方式，在自己的服务器上完成 AFFiNE 的部署。

1. 准备工作

在开始之前，请确保你的服务器满足以下最低要求：

操作系统：Linux（Ubuntu 20.04+、Debian 11+ 等）或通过 WSL2 运行的 Windows。
硬件：至少 4 GB RAM 和 2个 CPU 核心。对于生产环境，推荐 8 GB+ RAM 和 4+ 核心。
存储：至少 20 GB 可用磁盘空间（实际需求取决于上传的图片和文件量）。
软件：已安装 Docker Engine 24.0+ 和 Docker Compose V2（可通过 docker compose version 验证）。

💡 数据主权提醒：自托管 AFFiNE 意味着你需要自行管理 PostgreSQL 数据库、Redis 缓存、上传的文件以及配置与备份。请评估自身运维能力后再做选择。

2. 部署 AFFiNE 服务器

官方强烈推荐使用 Docker Compose 进行部署，它将 AFFiNE 应用、PostgreSQL 数据库、Redis 缓存和数据库迁移任务打包在一个可重复的堆栈中。

2.1 创建部署目录并下载配置文件

首先，创建一个稳定的目录来存放所有数据，并进入该目录：

1 2	mkdir ~/affine cd ~/affine

官方 Compose 文件默认将 PostgreSQL 数据、上传文件和配置存储在相对于此目录的子文件夹中，因此请勿随意移动或删除此目录。

然后，使用 wget 或 curl 下载官方提供的最新 docker-compose.yml 和配置文件模板：

# 下载 Docker Compose 文件
wget -O docker-compose.yml https://github.com/toeverything/AFFiNE/releases/latest/download/docker-compose.yml

# 创建配置目录并下载配置文件模板
mkdir -p config
wget -O config/config.json https://github.com/toeverything/AFFiNE/releases/latest/download/config.json.example

注意：官方最新的 Docker Compose 部署不再需要 .env 文件来配置运行时参数。所有应用设置应存放在 config/config.json 中。

2.2 配置应用参数（config.json）

使用文本编辑器（如 nano 或 vim）打开 config/config.json 文件：

1	nano config/config.json

你至少需要修改 server.externalUrl 字段，将其设置为用户将用来访问此实例的最终 URL。

示例配置（本地测试）：

{
  "$schema": "https://github.com/toeverything/affine/releases/latest/download/config.schema.json",
  "server": {
    "name": "我的 AFFiNE 工作区",
    "externalUrl": "http://localhost:3010"
  },
  "copilot": {
    "enabled": true
  }
}

server.externalUrl：必须与实际访问地址一致。如果后续配置了域名和 HTTPS，请修改为 https://你的域名。
copilot.enabled：设为 true 可以启用 AFFiNE AI 功能（需自行配置 API 密钥）。

保存并退出编辑器。

2.3 启动 AFFiNE 服务

在 ~/affine 目录下，执行以下命令以守护进程模式启动所有容器：

1	docker compose up -d

首次启动时，Docker 会自动拉取 AFFiNE、PostgreSQL 和 Redis 的镜像，这可能需要几分钟时间。

执行后，通过以下命令检查服务状态：

1	docker compose ps

你应该会看到 affine、postgres、redis 和 affine_migration（一次性任务，完成后会退出）等容器。

如果启动过程中出现问题，可以查看日志：

1	docker compose logs --tail=200 affine affine_migration

3. 次配置与使用

3.1 访问并注册管理员账户

在浏览器中访问 http://<你的服务器IP地址>:3010（如果是在本地部署，则为 http://localhost:3010）。
页面加载后，按照提示创建第一个管理员账户。该账户拥有最高管理权限。

3.2 后续配置建议

管理后台：登录后，你可以访问 http://<你的地址>:3010/admin/settings 对服务器进行更多设置，如修改站点名称、配置邮件服务等。
域名与 HTTPS：在生产环境中，强烈建议你配置反向代理（如 Nginx、Traefik）并提供 HTTPS 访问。你需要将 config.json 中的 server.externalUrl 更新为 https://你的域名。
启用全文搜索：从 AFFiNE 0.22 版本开始，你可以通过添加一个 Manticore 搜索服务容器来启用服务端全文搜索。这需要额外配置 docker-compose.indexer.yml 文件。