AFFiNE 0.27.4 Docker Compose 部署指南

目标：在一台 Ubuntu 服务器上以官方 Docker Compose 结构完整部署 AFFiNE 0.27.4（allinone 应用 + 一次性迁移任务 + PostgreSQL 16/pgvector + Redis 7），覆盖版本与镜像选型、端口与网段复核、应用配置（config.json）、首次管理员初始化、GraphQL/Blob 功能验证、重启持久化验证、等价 docker run 与常见问题排障。本文全部命令与回显均来自 2026-10-25 的真实部署实测；组件背景与选型对比见《AFFiNE 0.27.4 介绍与选型指南》，逐项配置参数见《AFFiNE 0.27.4 配置参数详解》。

一、环境信息

项目	值
服务器 IP（内网）	192.168.146.128（网卡 ens33）
操作系统	Ubuntu Linux（内核 6.x，x86_64）
Docker 版本	29.9.2
Docker Compose 版本	v5.6.1
AFFiNE 版本	0.27.4（官方服务端镜像 `ghcr.io/toeverything/affine:0.27.4`，体积约 895 MB）
数据库	PostgreSQL 16（`pgvector/pgvector:pg16`，约 631 MB，自带 pgvector 扩展）
缓存/队列	Redis 7（`redis:7`，实测运行 7.4.11，standalone）
部署目录	`/opt/data/quzuo/tmp/affine/deploy/`（数据落盘 `./data`，配置 `./config`）
Compose 项目名	`affine-v0274-stack`（显式 `name:` 声明）
对外端口	8137 → 3010（启动前 `ss -ltn` 复核空闲）
自定义网段	10.89.56.0/24（bridge 网络 `affine-0.27.4-net`）
管理员账号	admin（admin@example.com）/ q1w2e3r4
应用访问地址	http://192.168.146.128:8137

二、版本与镜像选型说明

版本依据（2026-10-25 查询）：

AFFiNE 0.27.4：GitHub Releases 标记 Latest 的稳定 tag 为 v0.27.4（ Releases 页面顶部另有 v0.27.5-beta.2、v2026.10.23-canary.908 等预发布通道，生产不要采用）。官方 compose 中镜像 tag 为 stable（始终指向最新稳定版）；生产建议锁定具体版本 tag 0.27.4，避免 stable 漂移造成意外升级——两者均已实测存在于 GHCR。
服务端镜像只有一个：ghcr.io/toeverything/affine（allinone 形态，Web 前端 + 服务端 + 管理面板同包）。实测 /info 接口返回 "flavor":"allinone" 佐证。历史上社区流传的多镜像组合（affine-graphql、affine-admin 等）已被官方单镜像取代，不要再按旧教程拆分部署。
PostgreSQL 必须用 pgvector 镜像：官方 compose 默认 pgvector/pgvector:pg16。pgvector 扩展是 AFFiNE AI 全量能力的前置；若使用自维护 PostgreSQL 需手动安装 pgvector。
Redis 7：官方要求 Redis 6.x 或 7.x，承担缓存、后台任务队列与同步基础设施，不可省略。

硬件要求（官方 Requirements 页，2026-10-25 查询）：最低 4 核 CPU + 2 GB 内存；有累计超 1 万词的大文档时建议 4 GB 内存（文档合并峰值约 1 GB）；服务端安装约需 1.5 GB 磁盘，数据另计。

三、前置条件

已安装 Docker（≥24）与 Docker Compose v2：

docker version --format '{{.Server.Version}}'
docker compose version --short

实测回显：

29.9.2
5.6.1

端口复核：确认拟用宿主端口 8137 空闲。

ss -ltn | grep ':8137'

无任何输出即为空闲（本批次 8128–8152 段内 8136 已被其他组件占用，故选 8137）。

网段复核：确认 10.89.56.0/24 未被既有 Docker 网络占用。

docker network ls --format '{{.Name}}' | while read n; do docker network inspect "$n" --format "$n {{range .IPAM.Config}}{{.Subnet}}{{end}}" 2>/dev/null; done | grep '10\.89\.'

实测回显（56 槽空闲，65/70 已被同机其他组件占用）：

solara-v216-stack_solara-net 10.89.65.0/24
rustdesk-1.1.16-net 10.89.70.0/24

拉取镜像：GHCR 为国外仓库，本环境 Docker 守护进程已配置代理可直接拉取：

docker pull ghcr.io/toeverything/affine:0.27.4
docker pull pgvector/pgvector:pg16
docker pull redis:7

⚠️ 注意：若 docker pull ghcr.io/toeverything/affine:0.27.4 超时失败，说明守护进程未配代理，可按官方文档为 Docker 配置 HTTP 代理后重试；镜像体积较大（affine 约 895 MB），需预留拉取时间。

四、部署步骤

4.1 创建部署目录

mkdir -p /opt/data/quzuo/tmp/affine/deploy/{config,data}
cd /opt/data/quzuo/tmp/affine/deploy

官方约定：PostgreSQL 数据落 ./data/postgres，上传文件落 ./data/storage，应用配置落 ./config，三者相对部署目录固定，不要中途挪动。

4.2 编写 docker-compose.yml

官方 compose 随每个稳定版 Release 发布（https://github.com/toeverything/AFFiNE/releases/latest/download/docker-compose.yml）。本文在官方文件基础上做四处生产化适配：显式项目名、锁定版本 tag、宿主端口 8137、PostgreSQL 口令认证、固定网段。完整文件如下：

name: affine-v0274-stack

services:
  affine:
    image: ghcr.io/toeverything/affine:0.27.4
    container_name: affine-0.27.4-server
    ports:
      - '8137:3010'
    depends_on:
      redis:
        condition: service_healthy
      postgres:
        condition: service_healthy
      affine_migration:
        condition: service_completed_successfully
    volumes:
      - ./data/storage:/root/.affine/storage
      - ./config:/root/.affine/config
    environment:
      - REDIS_SERVER_HOST=redis
      - DATABASE_URL=postgresql://affine:q1w2e3r4@postgres:5432/affine
      - AFFINE_INDEXER_ENABLED=false
    restart: unless-stopped
    networks:
      - affine-net

  affine_migration:
    image: ghcr.io/toeverything/affine:0.27.4
    container_name: affine-0.27.4-migration
    volumes:
      - ./data/storage:/root/.affine/storage
      - ./config:/root/.affine/config
    command: ['sh', '-c', 'node ./scripts/self-host-predeploy.js']
    environment:
      - REDIS_SERVER_HOST=redis
      - DATABASE_URL=postgresql://affine:q1w2e3r4@postgres:5432/affine
      - AFFINE_INDEXER_ENABLED=false
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    networks:
      - affine-net

  redis:
    image: redis:7
    container_name: affine-0.27.4-redis
    healthcheck:
      test: ['CMD', 'redis-cli', '--raw', 'incr', 'ping']
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped
    networks:
      - affine-net

  postgres:
    image: pgvector/pgvector:pg16
    container_name: affine-0.27.4-postgres
    volumes:
      - ./data/postgres:/var/lib/postgresql/data
    environment:
      POSTGRES_USER: affine
      POSTGRES_PASSWORD: q1w2e3r4
      POSTGRES_DB: affine
      POSTGRES_INITDB_ARGS: '--data-checksums'
    healthcheck:
      test: ['CMD', 'pg_isready', '-U', 'affine', '-d', 'affine']
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped
    networks:
      - affine-net

networks:
  affine-net:
    name: affine-0.27.4-net
    driver: bridge
    ipam:
      config:
        - subnet: 10.89.56.0/24

四个服务的职责与依赖链：postgres/redis 先起并通过健康检查 → affine_migration 执行数据库迁移后退出 → affine 主服务最后启动并监听 3010（映射到宿主 8137）。

⚠️ 注意：官方原版的 PostgreSQL 使用 POSTGRES_HOST_AUTH_METHOD: trust 免密（仅内网互信）。本文按生产实践改为口令认证（q1w2e3r4），DATABASE_URL 中同步携带口令；两者必须一致，否则迁移服务连库失败。

4.3 创建应用配置 config/config.json

0.27 起 AFFiNE 的首选配置来源是 config/config.json（不再需要 .env）。最小可用配置：

{
  "$schema": "https://github.com/toeverything/affine/releases/latest/download/config.schema.json",
  "server": {
    "name": "AFFiNE Self-hosted",
    "externalUrl": "http://192.168.146.128:8137"
  },
  "copilot": {
    "enabled": true,
    "byok": {
      "enabled": true,
      "allowCustomEndpoint": true
    }
  }
}

⚠️ 注意：server.externalUrl 必须填用户最终访问本实例的完整 URL（含端口）。配错会导致登录跳转、分享链接、桌面端连接全部指向错误地址。该项及其他全部参数的逐项说明见《AFFiNE 0.27.4 配置参数详解》。

4.4 启动服务栈

cd /opt/data/quzuo/tmp/affine/deploy
docker compose up -d
docker compose ps

实测回显（启动编排自动按依赖顺序执行）：

 Network affine-0.27.4-net  Created
 Container affine-0.27.4-postgres  Healthy
 Container affine-0.27.4-redis  Healthy
 Container affine-0.27.4-migration  Exited
 Container affine-0.27.4-server  Started

docker compose ps 实测：

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 Less than a second     0.0.0.0:8137->3010/tcp, [::]:8137->3010/tcp

迁移服务是一次性任务，Exited 为正常终态。查看迁移日志确认全部迁移完成：

docker compose logs affine_migration | tail -15

实测回显（节选，10 项迁移全部 ✔，收尾 Done in 1.43s.）：

affine-0.27.4-migration  | [Nest] 188  -  10/25/2026, 4:17:07 AM     LOG [RunCommand] Done 10 migrations
affine-0.27.4-migration  | [Nest] 188  -  10/25/2026, 4:17:07 AM     LOG [RunCommand]   ✔ Guid1698398506533
affine-0.27.4-migration  | [Nest] 188  -  10/25/2026, 4:17:07 AM     LOG [RunCommand]   ✔ UnamedAccount1703756315970
affine-0.27.4-migration  | [Nest] 188  -  10/25/2026, 4:17:07 AM     LOG [RunCommand]   ✔ CreateIndexerTables1745211351719
affine-0.27.4-migration  | [Nest] 188  -  10/25/2026, 4:17:07 AM     LOG [RunCommand]   ✔ CorrectSessionUpdateTime1751966744168
affine-0.27.4-migration  | [Nest] 188  -  10/25/2026, 4:17:07 AM     LOG [RunCommand]   ✔ ConvergeManagedProviderProfiles1786810000000
affine-0.27.4-migration  | Done in 1.43s.

主服务日志关键行：

docker compose logs affine | tail -5

实测回显：

affine-0.27.4-server  | [Nest] 1  -  10/25/2026, 4:17:09 AM     LOG [NestApplication] Nest application successfully started
affine-0.27.4-server  | [Nest] 1  -  10/25/2026, 4:17:09 AM     LOG [WorkspaceResolver] AFFiNE Server is running in [selfhosted] mode
affine-0.27.4-server  | [Nest] 1  -  10/25/2026, 4:17:09 AM     LOG [WorkspaceResolver] Listening on http://0.0.0.0:3010
affine-0.27.4-server  | [Nest] 1  -  10/25/2026, 4:17:09 AM     LOG [WorkspaceResolver] And the public server should be recognized as http://192.168.146.128:8137

最后一行证明 server.externalUrl 已生效。

4.5 首次初始化：创建管理员账号

服务刚启动时实例处于未初始化状态，访问首页会被重定向到安装向导：

curl -sI http://192.168.146.128:8137/ | head -4

实测回显：

HTTP/1.1 302 Found
X-Powered-By: Express
Location: /admin/setup
Content-Type: text/plain; charset=utf-8

浏览器打开 http://192.168.146.128:8137/admin/setup，按向导填写首个管理员：姓名 admin、邮箱 admin@example.com、密码 q1w2e3r4。该向导底层调用 POST /api/setup/create-admin-user，用 curl 等价完成：

curl -s -X POST http://192.168.146.128:8137/api/setup/create-admin-user \
  -H 'Content-Type: application/json' \
  -d '{"name":"admin","email":"admin@example.com","password":"q1w2e3r4"}'

实测回显：

{"id":"38ccef6f-61d0-4a00-ae0b-da659babdf06","email":"admin@example.com","name":"admin"}

初始化完成后实例状态翻转：

curl -s http://192.168.146.128:8137/graphql -H 'Content-Type: application/json' \
  -d '{"query":"{ serverConfig { initialized name baseUrl version } }"}'

实测回显：

{"data":{"serverConfig":{"initialized":true,"name":"AFFiNE Self-hosted","baseUrl":"http://192.168.146.128:8137","version":"0.27.4"}}}

4.6 功能验证（登录 → 建工作区 → 上传文件）

登录取会话：

curl -s -X POST http://192.168.146.128:8137/api/auth/sign-in \
  -H 'Content-Type: application/json' \
  -d '{"email":"admin@example.com","password":"q1w2e3r4"}' \
  -c /tmp/affine-cookie.txt -o /dev/null -w 'HTTP %{http_code}\n'

实测回显：HTTP 200（响应同时种下 affine_session 等 3 个 Cookie）。

创建工作区（GraphQL 上传初始化文档快照）：

printf '\x00\x00' > /tmp/affine-init.bin
curl -s http://192.168.146.128:8137/graphql -b /tmp/affine-cookie.txt \
  -H 'Origin: http://192.168.146.128:8137' \
  -F 'operations={"query":"mutation($init: Upload!){createWorkspace(init:$init){id}}","variables":{"init":null}}' \
  -F 'map={"0":["variables.init"]}' \
  -F '0=@/tmp/affine-init.bin'

实测回显：

{"data":{"createWorkspace":{"id":"5eac931b-4b57-4684-9829-6f1cea8f4bd3"}}}

💡 说明：AFFiNE 的「文档/白板」在服务端统一是工作区内的 CRDT 文档快照，浏览器里新建文档与白板页面后数据即经同步落库；上一步创建的工作区就是它们的载体。日常使用中直接在 Web 界面操作即可，本节用 API 实测是为了给出可复现的验证手段。

上传文件验证 Blob 存储（以头像为例）：

curl -s http://192.168.146.128:8137/graphql -b /tmp/affine-cookie.txt \
  -H 'Origin: http://192.168.146.128:8137' \
  -F 'operations={"query":"mutation($avatar: Upload!){uploadAvatar(avatar:$avatar){avatarUrl}}","variables":{"avatar":null}}' \
  -F 'map={"0":["variables.avatar"]}' \
  -F '0=@/tmp/avatar.png;type=image/png'

实测回显：

{"data":{"uploadAvatar":{"avatarUrl":"http://192.168.146.128:8137/api/avatars/38ccef6f-61d0-4a00-ae0b-da659babdf06-avatar-1792902086797"}}}

文件随即落盘到 ./data/storage/avatars/（见五章）。浏览器访问该 avatarUrl 实测返回 200 image/webp（服务端做了图片转码）。

4.7 重启持久化验证

docker compose restart

待服务恢复后重新登录并复查数据：

curl -s -X POST http://192.168.146.128:8137/api/auth/sign-in \
  -H 'Content-Type: application/json' \
  -d '{"email":"admin@example.com","password":"q1w2e3r4"}' -o /dev/null -w 'HTTP %{http_code}\n'
curl -s http://192.168.146.128:8137/graphql -b /tmp/affine-cookie.txt \
  -H 'Content-Type: application/json' \
  -d '{"query":"{ workspace(id: \"5eac931b-4b57-4684-9829-6f1cea8f4bd3\") { id createdAt } }"}'
curl -s -o /dev/null -w '%{http_code} %{content_type}\n' \
  http://192.168.146.128:8137/api/avatars/38ccef6f-61d0-4a00-ae0b-da659babdf06-avatar-1792902086797

实测回显（重启后登录成功、工作区创建时间不变、头像仍可访问，持久化成立）：

HTTP 200
{"data":{"workspace":{"id":"5eac931b-4b57-4684-9829-6f1cea8f4bd3","createdAt":"2026-10-25T04:20:56.918Z"}}}
200 image/webp

⚠️ 注意：docker compose restart 会连带重启一次性迁移服务，迁移是幂等的（实测重跑 1.36s 正常退出），不影响数据；升级版本时也应让迁移服务再跑一次（见《AFFiNE 日常运维手册》升级章节）。

五、数据持久化说明

三个挂载目录即全部状态，备份与迁移只需接管它们：

目录（部署目录下）	挂载点	内容	实测占用
`./data/postgres`	`/var/lib/postgresql/data`	全部结构化数据：用户、工作区、文档 CRDT 快照、权限、配置（实测初始化后 91 张表）	69 MB
`./data/storage`	`/root/.affine/storage`	Blob 文件：头像、文档附件、图片（实测头像落盘为 `<id>` 本体 + `<id>.metadata.json`）	16 KB
`./config`	`/root/.affine/config`	`config.json` 应用配置 + 自动生成的 `private.key` 签名私钥	12 KB

实测数据库内容抽样：

docker exec affine-0.27.4-postgres psql -U affine -d affine -t -c 'select email,name from users;'

回显：

 admin@example.com | admin

⚠️ 注意：config/private.key 由迁移服务首次运行自动生成（官方明确：不要手动设置 AFFINE_PRIVATE_KEY）。该文件必须随备份一起保存，替换它会导致已签名/加密数据（会话令牌等）失效。

六、环境变量表

0.27 起环境变量只承担「服务接线」职责，应用配置一律走 config.json。当前支持的环境变量（官方 Environment Variables 参考页，2026-10-25 查询）：

变量	默认值	说明
`DATABASE_URL`	无（compose 内置）	PostgreSQL 连接串，格式 `postgresql://user:password@postgres:5432/affine`；口令含特殊字符需 URL 编码
`REDIS_SERVER_HOST`	localhost	Redis 主机
`REDIS_SERVER_PORT`	6379	Redis 端口
`REDIS_SERVER_USERNAME`	空	Redis 用户名（ACL）
`REDIS_SERVER_PASSWORD`	空	Redis 密码
`REDIS_SERVER_DATABASE`	0	首个逻辑库序号；AFFiNE 会连用该序号起的 5 个库
`LISTEN_ADDR`	0.0.0.0	服务进程监听地址
`AFFINE_SERVER_PORT`	3010	服务进程监听端口（只改进程端口；宿主端口改 compose 映射）
`AFFINE_INDEXER_ENABLED`	见配置	索引器开关（官方 compose 默认 false）

已废弃变量（0.27 官方 compose 不再读取，不要照抄旧教程）：AFFINE_REVISION（镜像 tag 已直接写在 compose）、PORT（改端口映射）、DB_DATA_LOCATION/UPLOAD_LOCATION/CONFIG_LOCATION（目录已固定为 ./data/postgres、./data/storage、./config）、DB_USERNAME/DB_PASSWORD/DB_DATABASE（并入 DATABASE_URL）。

兼容别名（仍可被解析，但新部署应改用 config.json 键）：AFFINE_SERVER_EXTERNAL_URL→server.externalUrl、AFFINE_SERVER_HTTPS→server.https、MAILER_HOST→mailer.SMTP.host 等，完整对照表见《AFFiNE 0.27.4 配置参数详解》。

七、配置参数说明

config/config.json 的主要配置域（基于官方 config.schema.json 实测列举）：server（名称/externalUrl/https/端口/子路径）、auth（注册开关/会话 TTL/密码强度）、mailer（SMTP 与备用 SMTP）、storages（avatar/blob 存储后端，可切 S3 兼容）、copilot（AI 开关与 BYOK）、indexer（全文检索外接 Elasticsearch/Manticore）、oauth（Google/GitHub/OIDC/Apple）、telemetry、throttle（限流）、websocket、payment（Team License 相关）等。

每个域的键、默认值与示例逐项见《AFFiNE 0.27.4 配置参数详解》。本文只强调部署期最关键的三项：

server.externalUrl：对外完整 URL（4.3 节已配置）。
server.name：实例名称，显示在管理面板与分享页。
copilot.byok.enabled：开启后用户可自带 AI API Key。

改完 config.json 需重启主服务生效：docker compose restart affine。

八、配置文件挂载

compose 中两条 volumes 把宿主目录挂进服务：

- ./data/storage:/root/.affine/storage   # Blob 存储（上传文件）
- ./config:/root/.affine/config          # 应用配置目录（config.json、private.key）

修改 config/config.json 直接编辑宿主文件即可，重启后生效，无需进入服务内部。
不要向 ./config 放入无关文件；private.key 自动生成、自动持久化在该目录。
若改用 S3 兼容存储（config.json 的 storages.blob），./data/storage 仅保留头像等本地项。

九、等价 docker run

不用 compose 时，四段等价命令（先建网络）：

docker network create -d bridge --subnet 10.89.56.0/24 affine-0.27.4-net

docker run -d --name affine-0.27.4-postgres --network affine-0.27.4-net \
  -v /opt/data/quzuo/tmp/affine/deploy/data/postgres:/var/lib/postgresql/data \
  -e POSTGRES_USER=affine -e POSTGRES_PASSWORD=q1w2e3r4 -e POSTGRES_DB=affine \
  -e POSTGRES_INITDB_ARGS=--data-checksums \
  --restart unless-stopped pgvector/pgvector:pg16

docker run -d --name affine-0.27.4-redis --network affine-0.27.4-net \
  --restart unless-stopped redis:7

# 待 postgres/redis 就绪后先跑一次性迁移
docker run --rm --name affine-0.27.4-migration --network affine-0.27.4-net \
  -v /opt/data/quzuo/tmp/affine/deploy/data/storage:/root/.affine/storage \
  -v /opt/data/quzuo/tmp/affine/deploy/config:/root/.affine/config \
  -e REDIS_SERVER_HOST=redis \
  -e DATABASE_URL=postgresql://affine:q1w2e3r4@postgres:5432/affine \
  -e AFFINE_INDEXER_ENABLED=false \
  ghcr.io/toeverything/affine:0.27.4 sh -c 'node ./scripts/self-host-predeploy.js'

docker run -d --name affine-0.27.4-server --network affine-0.27.4-net \
  -p 8137:3010 \
  -v /opt/data/quzuo/tmp/affine/deploy/data/storage:/root/.affine/storage \
  -v /opt/data/quzuo/tmp/affine/deploy/config:/root/.affine/config \
  -e REDIS_SERVER_HOST=redis \
  -e DATABASE_URL=postgresql://affine:q1w2e3r4@postgres:5432/affine \
  -e AFFINE_INDEXER_ENABLED=false \
  --restart unless-stopped ghcr.io/toeverything/affine:0.27.4

💡 说明：compose 的 depends_on 健康检查编排（postgres/redis healthy → migration 完成 → server 启动）在纯 docker run 下需人工保证顺序：先等 pg_isready 与 redis-cli ping 通过，再跑迁移，最后起主服务。生产仍推荐 compose。

十、常用运维命令

cd /opt/data/quzuo/tmp/affine/deploy

docker compose ps                                   # 查看服务状态
docker compose logs -f affine                       # 跟踪主服务日志
docker compose logs --tail=200 affine affine_migration   # 排查启动/迁移问题（官方推荐用法）
docker compose restart affine                       # 改了 config.json 后重启主服务
docker compose stop && docker compose start         # 停止/启动整栈（数据保留）
docker compose down                                 # 停止并删除服务与默认网络（数据目录保留）

docker exec affine-0.27.4-postgres psql -U affine -d affine -c '\dt'   # 进库查表
docker exec affine-0.27.4-redis redis-cli info server | grep redis_version  # 查 Redis 版本

升级版本（改 compose 中两处镜像 tag 后）：

docker compose pull && docker compose up -d

十一、常见问题

Q1：docker compose up -d 后 affine 服务一直未启动？ 先看依赖链哪一环卡住：docker compose ps 中 postgres/redis 必须 (healthy)、migration 必须 Exited (0)。用 docker compose logs --tail=200 affine affine_migration 定位。最常见原因是 DATABASE_URL 口令与 PostgreSQL 口令不一致（迁移日志出现认证失败）。

Q2：日志出现 role "affine" does not exist？ 官方 Upgrade 页收录的典型问题：./data/postgres 目录被旧实例污染或 POSTGRES_USER 与历史不一致。空数据场景直接清空 ./data/postgres 重建；有数据场景按官方 Postgres 管理页修复角色。

Q3：日志警告 Mailer SMTP transport is not configured.？ 未配置 SMTP 的正常提示（实测复现），不影响使用；只是邀请邮件、密码重置邮件不可用。需要邮件时在 config.json 配 mailer.SMTP，见配置详解篇。

Q4：首次打开页面白屏或跳到错误域名？ server.externalUrl 与实际访问地址不一致。改为最终 URL（含端口）后 docker compose restart affine。

Q5：忘记管理员密码？ 管理面板（/admin）登录后可对用户执行密码重置；或调用 sendSetPasswordEmail（需 SMTP）。完全无法进入时可在数据库 users 表核实账号状态，再决定是否重建实例。

Q6：客户端连不上自托管实例？ 确认桌面客户端版本 ≥0.26：0.27 服务端按官方兼容矩阵拒绝 0.26 以下客户端（0.27 Release Notes 的 Breaking Change）。

Q7：拉取 GHCR 镜像超时？ GHCR 在国内网络下不稳定。为 Docker 守护进程配置 HTTP 代理后重试 docker compose pull；离线环境可在可联网机器 docker save 后 docker load 导入。

Q8：全文检索/AI 搜索不可用？ 官方 compose 默认 AFFINE_INDEXER_ENABLED=false，且未外接 Elasticsearch/Manticore。需要时在 config.json 开启 indexer 域并接入检索后端，见配置详解篇。

十二、参考链接

官方自托管文档首页：https://docs.affine.pro/self-host-affine
Docker Compose 安装页：https://docs.affine.pro/self-host-affine/install/docker-compose-recommended
硬件与依赖要求：https://docs.affine.pro/self-host-affine/install/requirements
环境变量参考：https://docs.affine.pro/self-host-affine/references/environment-variables
官方 compose 参考全文：https://docs.affine.pro/self-host-affine/references/docker-compose-yml
升级指南：https://docs.affine.pro/self-host-affine/install/upgrade
稳定版 Release v0.27.4：https://github.com/toeverything/AFFiNE/releases/tag/v0.27.4