AppFlowy 0.19.10 Docker Compose 部署指南

AppFlowy 自托管服务端 Docker Compose 部署实战：Docker 环境安装与排障、镜像版本固定（含 MinIO 分发停摆取证）、.env 配置、11 服务栈启动与健康验证、数据持久化、运维升级与 FAQ，全部命令 Ubuntu 22.04 实测通过。

AppFlowy自动化部署知识库协作编辑人工智能2026/10/23

AppFlowy 0.19.10 Docker Compose 部署指南

目标：在 Ubuntu 22.04 服务器上用官方 Docker Compose 从零部署一套可用的 AppFlowy 自托管服务端（AppFlowy Cloud 0.19.10 全家桶），覆盖 Docker 环境安装、镜像版本固定、.env 配置、启动与健康验证、数据持久化、日常运维与升级回滚。本文全部命令与回显已在 Ubuntu 22.04（amd64）+ Docker Compose 环境实测通过，服务端版本 0.19.10（2026-10-22 官方最新稳定版）。

一、环境信息

  • 操作系统：Ubuntu 22.04 LTS（amd64，实测环境为最小化安装后加装 Docker Engine）；
  • Docker Engine：29.8.1（部署实测）；全新安装实测为 29.9.2（版本随官方源滚动，≥24 均可）；
  • Docker Compose：v5.5.1（部署实测）；全新安装实测为 v5.6.1（v2 插件形态均可）；
  • AppFlowy 服务端：AppFlowy Cloud 0.19.10（Docker Hub appflowyinc/appflowy_cloud 最新稳定 tag，镜像更新 2026-10-20）；
  • 配套镜像版本（2026-10-22 查证自 Docker Hub，全部在 .env 中固定）：
    组件镜像固定 tag
    主服务appflowyinc/appflowy_cloud0.19.10
    认证appflowyinc/gotrue0.18.11
    管理台appflowyinc/admin_frontend0.19.3
    AI 服务appflowyinc/appflowy_ai0.17.7
    后台任务appflowyinc/appflowy_worker0.19.10
    检索服务appflowyinc/appflowy_search0.19.10
    Web 客户端appflowyinc/appflowy_web0.19.23
    数据库pgvector/pgvectorpg16（实测内核 PostgreSQL 16.15，pgvector 扩展 0.8.7）
    缓存redislatest（实测 Redis server v=8.10.2）
    对象存储minio/miniolatest（⚠️ 分发现状见第二章）
    反向代理nginxlatest
  • 部署目录：/opt/appflowy/appflowy-cloud（本实测路径，可按需调整）；
  • 对外端口：80（HTTP，可改）、443（TLS，可选）；
  • Compose 项目名：appflowy-0.19.10-stack。

二、镜像选型说明

2.1 官方镜像清单

AppFlowy Cloud 官方部署物为仓库根目录的 docker-compose.yml，编排 11 个服务（业务服务 7 个由 appflowyinc/* 官方镜像提供，基础设施 4 个用官方上游镜像）。镜像版本通过 .env 中的 *_VERSION 变量固定，docker-compose.yml 中的默认引用形如：

image: appflowyinc/appflowy_cloud:${APPFLOWY_CLOUD_VERSION:-latest}
image: appflowyinc/gotrue:${GOTRUE_VERSION:-latest}
image: pgvector/pgvector:pg16

💡 说明：pgvector/pgvector:pg16 是内置 pgvector 向量扩展的 PostgreSQL 16 构建物——AppFlowy 的语义检索依赖 vector 扩展，不能用普通 postgres:16 替换，实测部署后扩展列表为 plpgsql 1.0 / uuid-ossp 1.1 / vector 0.8.7 / pgcrypto 1.3。

2.2 版本固定建议

官方 compose 默认 latest，生产部署强烈建议在 .env 固定版本（本文实测值即 2026-10-22 官方最新稳定版）：

APPFLOWY_CLOUD_VERSION=0.19.10
GOTRUE_VERSION=0.18.11
APPFLOWY_ADMIN_FRONTEND_VERSION=0.19.3
APPFLOWY_AI_VERSION=0.17.7
APPFLOWY_WORKER_VERSION=0.19.10
APPFLOWY_SEARCH_VERSION=0.19.10
APPFLOWY_WEB_VERSION=0.19.23

⚠️ 注意：客户端与服务端有配套要求——AppFlowy 桌面客户端 v0.14.10 要求服务端 ≥ 0.19.10（官方发布说明原文："Self-hosted workspaces require AppFlowy Cloud v0.19.10 or later"）。升级客户端前先升级服务端。

2.3 MinIO 镜像分发现状（2026-10 实测，选型必读）

官方 compose 引用 minio/minio 镜像，但 MinIO 开源版分发状态在 2025 年 10 月后发生重大变化，本文实测（2026-10-22）证据如下：

  • https://dl.min.io/server/minio/release/linux-amd64/minio 返回 HTTP 410 Gone，响应正文声明："The open-source MinIO Server, MinIO Client (mc) and MinIO KES projects are archived and no longer maintained. MinIO does not provide product support, security updates, or security advisories"；
  • https://dl.min.io/ 首页仅剩 aistor（商业版 AIStor）与 logo 两个目录；
  • docker pull minio/minio:latest（含历史 RELEASE tag）返回 pull access denied for minio/minio, repository does not exist or may require 'docker login'；
  • quay.io/minio/minio 返回 401 UNAUTHORIZED；
  • GitHub minio/minio 仓库最后一次发布为 RELEASE.2025-10-15T17-29-55Z（Security/CVE 类），无二进制资产。

结论与可选路径：MinIO 开源服务端已归档、匿名分发通道全部关闭。部署官方 compose 时需满足以下之一：

  1. 已有存量镜像/授权：企业已持有 MinIO 商业授权或本地缓存有 minio/minio 镜像的，原样使用（本文实测即使用缓存的 MinIO RELEASE.2024-12-18 构建物，重命名 tag 后官方 compose 零改动跑通）；
  2. 对接外部 S3：修改 .env 中 APPFLOWY_S3_USE_MINIO=false 并配置 AWS S3 或其他 S3 兼容服务；
  3. 评估 S3 兼容替代：自托管场景可评估 SeaweedFS、Garage 等仍在活跃分发的 S3 兼容实现（需自行适配 compose 与预签名端点）。

三、前置条件

3.1 服务器要求

  • 4 核 CPU / 8 GB 内存起步（11 个服务同机运行；AI 与检索服务未启用时可降配）；
  • 磁盘 ≥ 40 GB（PostgreSQL 数据 + 对象存储 + 镜像约 2 GB）；
  • Ubuntu 22.04 / 24.04 等 systemd 发行版，具备 sudo 权限；
  • 若面向公网，需域名与 TLS 证书（纯内网可先用 FQDN=localhost + HTTP 验证）。

3.2 安装 Docker Engine 与 Compose 插件（实测）

Ubuntu 22.04 全新环境按官方 apt 源安装（以下为实测命令与回显）：

# 安装依赖与 GPG 密钥
sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# 写入 apt 源（Ubuntu 22.04 代号 jammy）
echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu jammy stable" | sudo tee /etc/apt/sources.list.d/docker.list
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

实测安装完成后版本回显：

Docker version 29.9.2, build a82e528
Docker Compose version v5.6.1

⚠️ 排障实录：首次拉取 GPG 密钥时若网络中断，apt-get update 会报 NO_PUBKEY 7EA0A9C3F273FCD8 / The repository ... is not signed——这是 key 文件下载不完整所致（实测复现过）。解决办法：删除 /etc/apt/keyrings/docker.asc 重新 curl -fsSL 下载（必要时配置代理），确认文件开头为 PGP 公钥块（mQINBF...）后再 apt-get update。

安装后启动并设置开机自启：

sudo systemctl enable --now docker

# 验证
sudo systemctl is-active docker
active

3.3 获取官方部署物

sudo mkdir -p /opt/appflowy && cd /opt/appflowy
sudo git clone https://github.com/AppFlowy-IO/AppFlowy-Cloud.git appflowy-cloud
cd appflowy-cloud
ls docker-compose.yml deploy.env nginx/

实测目录内容：

docker-compose.yml  deploy.env  nginx/

四、部署步骤

4.1 生成 .env 并修改关键项

官方提供 340 行配置模板 deploy.env，复制为 .env 后修改（实测改动清单）：

cp deploy.env .env

必改项（生产安全基线）：

# 服务器域名（纯内网验证可用 localhost，客户端接入时换真实域名/IP）
FQDN=localhost
SCHEME=http
WS_SCHEME=ws

# 数据库口令（默认 password 必改）
POSTGRES_PASSWORD=q1w2e3r4

# GoTrue 管理员（服务首次启动时自动创建，用于登录 /console 管理台）
GOTRUE_ADMIN_EMAIL=admin@example.com
GOTRUE_ADMIN_PASSWORD=q1w2e3r4

# JWT 签名密钥（默认 hello456 必改，至少 32 字符随机串）
GOTRUE_JWT_SECRET=q1w2e3r4q1w2e3r4

# 对象存储口令（默认 minioadmin 必改）
AWS_ACCESS_KEY=q1w2e3r4minio
AWS_SECRET=q1w2e3r4minio

# 邮箱注册免验证（无 SMTP 时先开，生产建议配 SMTP 后改 false）
GOTRUE_MAILER_AUTOCONFIRM=true

# 版本固定（见 2.2 节）
APPFLOWY_CLOUD_VERSION=0.19.10
...

⚠️ 排障实录：.env 中未定义的变量会在 compose 执行时产生告警，实测输出节选：The "AZURE_OPENAI_API_KEY" variable is not set. Defaulting to a blank string.（AZURE_OPENAI_*、APPFLOWY_S3_REGION 等未用 Azure/S3 区域时的预期告警，不影响部署；追求干净日志可在 .env 中显式置空值）。

4.2 声明 Compose 项目名

为避免多套栈同名互扰，建议在 docker-compose.yml 顶部显式声明项目名：

name: appflowy-0.19.10-stack

💡 说明：项目名决定资源前缀（实测容器名为 appflowy-01910-stack-<服务>-1、卷名为 appflowy-01910-stack_<卷>），同一台机器跑多套 AppFlowy 环境时务必区分命名。

4.3 拉取镜像

docker compose pull

实测过程要点：7 个 appflowyinc/* 镜像与 pgvector/redis/nginx 正常拉取；minio/minio 报错（详见 2.3 节分发现状），使用已有镜像的部署在此步前需确保本机可解析到该镜像（导入或换源），否则 pull 中断：

Image appflowyinc/appflowy_cloud:0.19.10 Pulled
...
Error response from daemon: pull access denied for minio/minio, repository does not exist or may require 'docker login'

4.4 启动全栈

docker compose up -d

实测输出节选（服务按依赖关系与健康检查依次启动，appflowy_cloud 健康后才拉起 admin_frontend/worker/web/ai）：

 Container appflowy-01910-stack-gotrue-1 Healthy
 Container appflowy-01910-stack-postgres-1 Healthy
 Container appflowy-01910-stack-appflowy_cloud-1 Healthy
 Container appflowy-01910-stack-admin_frontend-1 Started
 Container appflowy-01910-stack-appflowy_worker-1 Started
 Container appflowy-01910-stack-appflowy_web-1 Started
 Container appflowy-01910-stack-ai-1 Started

启动后全量状态（实测 docker compose ps）：

NAME                                     IMAGE                                 STATUS
appflowy-01910-stack-admin_frontend-1    appflowyinc/admin_frontend:0.19.3     Up 3 minutes
appflowy-01910-stack-ai-1                appflowyinc/appflowy_ai:0.17.7        Up 3 minutes (healthy)
appflowy-01910-stack-appflowy_cloud-1    appflowyinc/appflowy_cloud:0.19.10    Up 3 minutes (healthy)
appflowy-01910-stack-appflowy_search-1   appflowyinc/appflowy_search:0.19.10   Up 2 minutes (healthy)
appflowy-01910-stack-appflowy_web-1      appflowyinc/appflowy_web:0.19.23      Up 3 minutes
appflowy-01910-stack-appflowy_worker-1   appflowyinc/appflowy_worker:0.19.10   Up 3 minutes
appflowy-01910-stack-gotrue-1            appflowyinc/gotrue:0.18.11            Up 3 minutes (healthy)
appflowy-01910-stack-minio-1             minio/minio                           Up 3 minutes (healthy)
appflowy-01910-stack-nginx-1             nginx                                 Up 3 minutes
appflowy-01910-stack-postgres-1          pgvector/pgvector:pg16                Up 3 minutes (healthy)
appflowy-01910-stack-redis-1             redis                                 Up 3 minutes

4.5 健康验证（实测回显）

# 主服务健康检查（返回字面量 OK）
curl http://127.0.0.1/api/health

OK

# 认证服务健康检查
curl http://127.0.0.1/gotrue/health

{"version":"","name":"GoTrue","description":"GoTrue is a user registration and authentication API"}

# MinIO 控制台路由（应返回 200）
curl -o /dev/null -w "%{http_code}\n" http://127.0.0.1/minio/
# Web 客户端（/ 302 跳转到 /app）
curl -o /dev/null -w "%{http_code} %{redirect_url}\n" http://127.0.0.1/
curl -o /dev/null -w "%{http_code} %{content_type}\n" -L http://127.0.0.1/app
# 管理控制台
curl -o /dev/null -w "%{http_code} %{content_type}\n" -L http://127.0.0.1/console

200
302 http://127.0.0.1/app
200 text/html
200 text/html; charset=utf-8

数据库侧验证（确认 AppFlowy 迁移与 pgvector 就位）：

docker compose exec postgres psql -U postgres -t -A -c "SELECT extname || ' ' || extversion FROM pg_extension"

plpgsql 1.0
uuid-ossp 1.1
vector 0.8.7
pgcrypto 1.3

💡 说明：数据库迁移由 appflowy_cloud 启动时自动执行（内置 sqlx 迁移集，共 64 个版本文件），gotrue 首次启动自动初始化 auth schema 并创建 GOTRUE_ADMIN_EMAIL 指定的管理员，无需手工导库。

4.6 端到端功能验证（注册 → 建档 → 工作区）

用 API 走通「注册用户 → 初始化档案 → 查看工作区」，验证全栈数据链路（实测）：

# 1. 注册终端用户（GOTRUE_MAILER_AUTOCONFIRM=true 时直接激活并返回 token）
curl -s -X POST http://127.0.0.1/gotrue/signup -H "Content-Type: application/json" -d '{"email":"user1@example.com","password":"q1w2e3r4"}'

{"access_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJlZDBkYzU0OC0...","token_type":"bearer","expires_in":604800,"expires_at":1793291446,"refresh_token":"...","user":{"id":"ed0dc548-9a65-4b00-bc50-e36c39b3715f","email":"user1@example.com",...}}

# 2. 触发用户建档（客户端登录后首个调用；此调用同时创建初始工作区）
TOKEN=<上一步 access_token>
curl -s http://127.0.0.1/api/user/verify/$TOKEN -H "Authorization: Bearer $TOKEN"

{"data":{"is_new":true},"code":0,"message":"Operation completed successfully."}

# 3. 查询工作区（应看到自动创建的 My Workspace，角色 Owner）
curl -s http://127.0.0.1/api/workspace -H "Authorization: Bearer $TOKEN"

{"data":[{"workspace_id":"cbaa42f8-d44a-4b66-b575-90c0f0682b81","database_storage_id":"6e3347fd-11cd-472f-9d54-4c5f1f26e702","owner_uid":649613791331356672,"owner_name":"user1@example.com","owner_email":"user1@example.com","workspace_type":0,"workspace_name":"My Workspace","created_at":"2026-10-22T16:31:43.091333Z","icon":"","member_count":1,"role":"Owner"}],"code":0,"message":"Operation completed successfully."}

服务端日志同步可见建档行为（实测日志节选）：

{"timestamp":"2026-10-22T16:31:43.099186Z","level":"INFO","fields":{"message":"Created new user in af_user: uid=649613791331356672, uuid=ed0dc548-9a65-4b00-bc50-e36c39b3715f, email=user1@example.com"}}

⚠️ 注意：GOTRUE_ADMIN_EMAIL 创建的是 GoTrue 侧管理员（角色 supabase_admin，用于登录 /console 管理台），不会自动在业务表 af_user 建档——用 admin@example.com 调 /api/user/profile 会得到 {"code":1024,"message":"User not found"}，属预期行为；终端用户必须走 /gotrue/signup + /api/user/verify/ 链路。

4.7 客户端接入

服务端就绪后，在 AppFlowy 桌面客户端（v0.14.10）登录界面选择「自托管 / Self-hosted」，服务器地址填 http://<服务器IP或域名>（生产为 https://<域名>），用注册的终端用户登录即可同步协作。浏览器直接访问 http://<服务器>/app 可使用 Web 客户端，/console 为管理台（用 GOTRUE_ADMIN_EMAIL 登录）。

五、数据持久化说明

全栈使用三个命名卷持久化数据（实测 docker volume ls）：

appflowy-01910-stack_keyword_index_data   # appflowy_search 关键词索引目录（容器内 /var/lib/appflowy/keyword_index）
appflowy-01910-stack_minio_data           # MinIO 对象存储（容器内 /data）
appflowy-01910-stack_postgres_data        # PostgreSQL 全部业务数据（容器内 /var/lib/postgresql/data）

要点：

  • 卷随 docker compose down 保留，down -v 才会删除——生产环境严禁随意 -v；
  • Postgres 单卷承载业务数据 + 协同快照 + 认证数据（auth schema）+ 向量索引，是备份核心；
  • 需要落盘到指定目录时，把 compose 中 postgres_data: 具名卷改为 bind mount（如 /opt/appflowy/data/postgres:/var/lib/postgresql/data）。

数据库备份实测（容器内 pg_dump）：

docker compose exec postgres pg_dump -U postgres -d postgres > appflowy-$(date +%F).sql

实测输出节选（标准 PostgreSQL 转储头）：

--
-- PostgreSQL database dump
--
\restrict ...
-- Dumped from database version 16.15 (Debian 16.15-1.pgdg12+2)

恢复：cat backup.sql | docker compose exec -T postgres psql -U postgres -d postgres（空库重建后执行）。

六、环境变量表（deploy.env 核心项实测清单）

分类变量实测值/默认值说明
基础FQDNlocalhost对外域名，客户端接入地址的组成部分
基础SCHEME / WS_SCHEMEhttp / ws启用 TLS 后改 https / wss
数据库POSTGRES_HOST / PORTpostgres / 5432compose 服务名内网寻址
数据库POSTGRES_USER / PASSWORD / DBpostgres / password / postgres口令必改；密码含特殊字符需 URL 编码后拼进 APPFLOWY_DATABASE_URL
认证GOTRUE_ADMIN_EMAIL / PASSWORDadmin@example.com / passwordGoTrue 管理员，首启自动创建，登录 /console
认证GOTRUE_JWT_SECREThello456JWT 签名密钥，gotrue 与 appflowy_cloud 必须一致，必改
认证GOTRUE_JWT_EXP604800token 有效期（秒），默认 7 天
认证GOTRUE_MAILER_AUTOCONFIRMtruetrue=注册免邮箱验证；配 SMTP 后改 false
认证GOTRUE_DISABLE_SIGNUPfalsetrue=仅受邀可加入
认证API_EXTERNAL_URL${APPFLOWY_BASE_URL}/gotrueGoTrue 对外地址（OAuth 回调基准）
认证GOTRUE_SMTP_*smtp.gmail.com 等邮箱验证邮件发送配置（HOST/PORT/USER/PASS/ADMIN_EMAIL）
OAuthGOTRUE_EXTERNAL_GOOGLE/GITHUB/DISCORD_ENABLEDfalse三方 OAuth 开关与 CLIENT_ID/SECRET/REDIRECT_URI
认证GOTRUE_SAML_ENABLED / PRIVATE_KEYfalse / 空SAML 2.0 企业 SSO
存储APPFLOWY_S3_USE_MINIOtruetrue=自托管 MinIO（path-style）；false=AWS S3
存储APPFLOWY_S3_CREATE_BUCKETtrue启动时自动建桶（生产建议 false+预建桶）
存储APPFLOWY_S3_MINIO_URLhttp://${MINIO_HOST}:${MINIO_PORT}MinIO 内网端点
存储APPFLOWY_S3_ACCESS_KEY / SECRET_KEY${AWS_ACCESS_KEY} / ${AWS_SECRET}对象存储凭据（默认 minioadmin 必改）
存储APPFLOWY_S3_BUCKETappflowy存储桶名
存储APPFLOWY_S3_PRESIGNED_URL_ENDPOINT${APPFLOWY_BASE_URL}/minio-api客户端直传预签名端点
AIAI_OPENAI_API_KEY空空=AI 功能关闭，核心功能不受影响
AIAI_SERVER_PORT / HOST5001 / aiAI 服务内网端口与服务名
AIAPPFLOWY_EMBEDDING_CHUNK_SIZE / OVERLAP2000 / 200语义检索分块参数
协同APPFLOWY_WEBSOCKET_MAILBOX_SIZE6000WebSocket 消息邮箱容量（内存与吞吐权衡）
协同APPFLOWY_COLLABORATE_MULTI_THREADfalse协同服务多线程开关
协同APPFLOWY_ACCESS_CONTROLtrue工作区/协同/实时权限控制总开关
协同APPFLOWY_DATABASE_MAX_CONNECTIONS40主服务 PG 连接池上限（PG 总连接默认约 100）
WebAPPFLOWY_WEB_URL${APPFLOWY_BASE_URL}Web 客户端地址
网络NGINX_PORT / NGINX_TLS_PORT80 / 443对外端口，被占用时改高位端口
网络RUST_LOGinfo主服务与 worker 日志级别
管理PGADMIN_DEFAULT_EMAIL / PASSWORDadmin@example.com / password可选 pgAdmin 组件凭据（extras 编排）

💡 说明：以上为日常运维高频子集；完整 340 行模板以官方 deploy.env 为准，逐参数深度解读见 《AppFlowy 0.19.10 配置参数详解》。

七、配置文件挂载

官方 compose 挂载两类本地文件，均相对部署目录：

nginx:
  volumes:
    - ./nginx/nginx.conf:/etc/nginx/nginx.conf
    - ./nginx/ssl/certificate.crt:/etc/nginx/ssl/certificate.crt
    - ./nginx/ssl/private_key.key:/etc/nginx/ssl/private_key.key
  • nginx/nginx.conf：统一入口路由（/gotrue、/api、/ws、/console、/minio、/minio-api、/ai、/）。上游地址以 nginx 变量形式写在 conf 中（set $appflowy_cloud_backend "http://appflowy_cloud:8000"; 等），自定义端口或跨机部署时改这里；
  • nginx/ssl/：仓库自带占位证书（自签样例），生产替换为真实证书（SCHEME=https、WS_SCHEME=wss 同步修改）；
  • 修改 conf 后需 docker compose restart nginx 生效（实测 restart 回显：Container appflowy-01910-stack-nginx-1 Restarting / Started）。

八、等价 docker run（单服务形态参考）

官方部署物是强依赖编排（gotrue 依赖 postgres 健康检查、appflowy_cloud 依赖 gotrue、其余服务依赖 appflowy_cloud），完整栈不适合逐个 docker run 手工拉起。仅给出核心服务的最小 docker run 形态便于理解（完整栈请用 compose）：

# 单独运行一个 appflowy_cloud 实例（需先具备 postgres/redis/gotrue/minio 并配齐环境变量）
docker run -d --name appflowy-cloud-test \
  -p 8000:8000 \
  -e APPFLOWY_ENVIRONMENT=production \
  -e APPFLOWY_DATABASE_URL=postgres://postgres:q1w2e3r4@postgres:5432/postgres \
  -e APPFLOWY_REDIS_URI=redis://redis:6379 \
  -e APPFLOWY_GOTRUE_JWT_SECRET=q1w2e3r4q1w2e3r4 \
  -e APPFLOWY_GOTRUE_BASE_URL=http://gotrue:9999 \
  -e APPFLOWY_S3_USE_MINIO=true \
  -e APPFLOWY_S3_ACCESS_KEY=q1w2e3r4minio \
  -e APPFLOWY_S3_SECRET_KEY=q1w2e3r4minio \
  --network appflowy-0.19.10-stack_default \
  appflowyinc/appflowy_cloud:0.19.10

💡 说明：该实例需加入既有 compose 网络（实测网络名 appflowy-0.19.10-stack_default）并复用其中 postgres/redis/gotrue 服务名寻址；健康检查端点为容器内 http://127.0.0.1:8000/api/health。

九、常用运维命令（实测）

cd /opt/appflowy/appflowy-cloud

docker compose ps                        # 状态总览（含 healthy 标记）
docker compose logs -f appflowy_cloud    # 跟随主服务日志（JSON 行格式）
docker compose logs --tail=100 gotrue    # 最近 100 行认证日志
docker compose stop appflowy_web         # 停单服务
docker compose start appflowy_web        # 起单服务
docker compose restart appflowy_cloud    # 重启单服务（改环境变量后生效用 up -d）
docker compose stop                      # 停全栈（数据卷保留）
docker compose up -d                     # 再起全栈
docker compose down                      # 删容器与网络（数据卷保留）

实测回显节选：

# stop 单服务
 Container appflowy-01910-stack-appflowy_web-1  Stopping
 Container appflowy-01910-stack-appflowy_web-1  Stopped
# restart
 Container appflowy-01910-stack-appflowy_cloud-1  Restarting
 Container appflowy-01910-stack-appflowy_cloud-1  Started

资源占用实测（docker stats --no-stream 节选，4C/31G 宿主、空载状态）：

NAME                                    CPU %   MEM USAGE
appflowy-01910-stack-postgres-1         0.13%   118.2MiB
appflowy-01910-stack-appflowy_cloud-1   0.53%   96.8MiB
appflowy-01910-stack-gotrue-1           0.05%   34.5MiB
appflowy-01910-stack-appflowy_search-1  0.31%   180.1MiB
appflowy-01910-stack-minio-1            0.21%   130.4MiB

十、升级与回滚

升级标准流程（客户端版本配套约束见 2.2 节）：

cd /opt/appflowy/appflowy-cloud
git pull                                  # 获取最新 compose 与迁移定义
# 编辑 .env 中的 *_VERSION 到新版本
docker compose pull
docker compose up -d                      # 滚动重建有变化的容器，数据卷保留

回滚：把 .env 版本改回上一稳定 tag，重复 pull + up -d。数据库回滚需配合备份（第五章 pg_dump），AppFlowy 迁移不保证向下兼容，升级前必做数据库备份。

十一、常见问题（FAQ）

Q1：docker compose pull 报 pull access denied for minio/minio 怎么办？ MinIO 开源版 2025-10 起归档并关闭匿名分发（实测证据链见 2.3 节：dl.min.io 410 / Docker Hub denied / Quay 401）。解决：使用已持有的存量镜像或商业授权镜像；或改用外部 S3（APPFLOWY_S3_USE_MINIO=false）；或评估 SeaweedFS/Garage 等 S3 兼容替代。

Q2：apt-get update 报 NO_PUBKEY 7EA0A9C3F273FCD8？ Docker 官方源 GPG 密钥文件下载不完整（实测在网络中断后复现）。重新下载 https://download.docker.com/linux/ubuntu/gpg 覆盖 /etc/apt/keyrings/docker.asc，确认文件为 PGP 公钥块后重试。

Q3：compose 运行时刷 The "AZURE_OPENAI_API_KEY" variable is not set 告警？ 未使用 Azure OpenAI 时的预期行为（默认空串），不影响功能。可在 .env 显式写 AZURE_OPENAI_API_KEY= 消除告警。

Q4：admin@example.com 调 API 报 User not found（code 1024）？ GoTrue 管理员与业务用户是两套体系：管理员只用于 /console 管理台登录，业务表 af_user 档案需终端用户经 /gotrue/signup + /api/user/verify/{token} 创建（实测行为，见 4.6 节）。

Q5：注册用户收不到验证邮件？ GOTRUE_MAILER_AUTOCONFIRM=true（免验证直通）时不发邮件；为 false 时需要正确配置 GOTRUE_SMTP_*，排查 docker compose logs gotrue。生产建议配置 SMTP 并恢复邮箱验证。

Q6：80/443 端口被占用？ .env 中改 NGINX_PORT=8131 等高位端口后 docker compose up -d 重建 nginx；客户端接入地址同步带端口号。

Q7：第二个用户注册后调 /api/user/verify/{token} 返回 code 1120「Seat limit reached」？ 0.19.10 官方镜像内置席位管控：未录入商业许可（af_self_host_commercial_license 表为空）时，全实例最多 1 个 Member/Owner 角色（实测第二个用户注册返回 {"code":1120,"message":"Seat limit reached: counted 1 Member/Owner users across initialized workspaces (limit 1)..."}）。单人使用不受影响；团队使用需通过管理台录入正式许可授权更多席位。

十二、参考链接