AppFlowy 0.19.10 配置参数详解

目标：系统梳理 AppFlowy 自托管服务端（AppFlowy Cloud 0.19.10 全家桶）的全部核心配置参数——配置文件定位、参数查看与修改方式、按组件分类的参数详解、可直接落地的生产配置模板，以及配置类常见问题。文中命令与回显均已在 Ubuntu 22.04 + AppFlowy Cloud 0.19.10 环境实测通过，版本查证日期 2026-10-22。

一、环境信息

• 操作系统：Ubuntu 22.04 LTS（amd64）；
• AppFlowy 服务端：AppFlowy Cloud 0.19.10（2026-10-20 发布，官方 Docker Hub 最新稳定 tag，2026-10-22 查证）；
• 配套组件版本（与《AppFlowy 0.19.10 介绍与选型指南》版本矩阵一致）：gotrue 0.18.11、admin_frontend 0.19.3、appflowy_ai 0.17.7、appflowy_worker / appflowy_search 0.19.10、appflowy_web 0.19.23、PostgreSQL 16.15（pgvector 0.8.7）、Redis 8.10.2；
• 配置载体：官方部署物以 .env 文件为唯一配置入口（源文件名为 deploy.env，部署时复制为 .env），由 Docker Compose 读取后注入各服务进程环境变量；源码部署形态则通过 systemd EnvironmentFile= 注入同一份变量集；
• 实测环境：AppFlowy Cloud 0.19.10 服务栈一套（11 服务全部 healthy），部署目录 /opt/appflowy/appflowy-cloud。

二、前置条件

• 已按《AppFlowy 0.19.10 Docker Compose 部署指南》或《Ubuntu 22.04 安装 AppFlowy 0.19.10 指南》完成一套 AppFlowy Cloud 服务端部署，服务处于运行状态；
• 具备服务器 root 或 sudo 权限，能编辑部署目录下的 .env 文件；
• Docker Compose 形态需 docker compose 命令可用；源码部署形态需 systemctl 可用。

三、参数查看与修改方式

3.1 配置文件定位

AppFlowy Cloud 官方仓库根目录提供 deploy.env 作为配置模板（340 行左右，带分组注释），部署时复制为 .env 使用：

cp deploy.env .env    # 官方部署第一步

.env 中大量变量以 ${VAR} 形式互相引用，Compose 在读取时会做一层展开，例如：

APPFLOWY_DATABASE_URL=postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@${POSTGRES_HOST}:${POSTGRES_PORT}/${POSTGRES_DB}
APPFLOWY_S3_ACCESS_KEY=${AWS_ACCESS_KEY}
APPFLOWY_S3_SECRET_KEY=${AWS_SECRET}

💡 因此排查配置问题时，要以「进程内实际生效的值」为准（见 3.2），不要只看 .env 表面文本。

3.2 查看进程实际生效的参数

以 Compose 形态为例，进入服务容器查看环境变量（下述回显为实测值）：

docker compose exec appflowy_cloud env | grep -E "^APPFLOWY_(DATABASE_URL|REDIS_URI|GOTRUE_BASE_URL|S3_USE_MINIO|S3_MINIO_URL|S3_BUCKET|ACCESS_CONTROL)=" | sort

实测回显：

APPFLOWY_ACCESS_CONTROL=true
APPFLOWY_DATABASE_URL=postgres://postgres:q1w2e3r4@postgres:5432/postgres
APPFLOWY_GOTRUE_BASE_URL=http://gotrue:9999
APPFLOWY_REDIS_URI=redis://redis:6379
APPFLOWY_S3_BUCKET=appflowy
APPFLOWY_S3_MINIO_URL=http://minio:9000
APPFLOWY_S3_USE_MINIO=true

gotrue 认证服务实际生效的参数：

docker compose exec gotrue env | grep -E "^(GOTRUE_DB_DRIVER|PORT|GOTRUE_SITE_URL|GOTRUE_MAILER_AUTOCONFIRM|GOTRUE_JWT_EXP|DATABASE_URL)="

实测回显：

DATABASE_URL=postgres://postgres:q1w2e3r4@postgres:5432/postgres?search_path=auth
PORT=9999
GOTRUE_SITE_URL=appflowy-flutter://
GOTRUE_DB_DRIVER=postgres
GOTRUE_JWT_EXP=604800
GOTRUE_MAILER_AUTOCONFIRM=true

后台任务服务实际生效的参数：

docker compose exec appflowy_worker env | grep -E "^(APPFLOWY_WORKER_(REDIS_URL|DATABASE_URL|DATABASE_NAME|IMPORT_TICK_INTERVAL)=|APPFLOWY_S3_BUCKET=)"

实测回显：

APPFLOWY_WORKER_REDIS_URL=redis://redis:6379
APPFLOWY_WORKER_DATABASE_NAME=postgres
APPFLOWY_WORKER_IMPORT_TICK_INTERVAL=30
APPFLOWY_S3_BUCKET=appflowy
APPFLOWY_WORKER_DATABASE_URL=postgres://postgres:q1w2e3r4@postgres:5432/postgres

⚠️ 注意两个「转换点」：其一，gotrue 进程读取的连接串变量名是 DATABASE_URL（由 compose 把 GOTRUE_DATABASE_URL 映射过去），且固定携带 ?search_path=auth，意味着 gotrue 的表全部位于 PostgreSQL 的 auth 模式；其二，.env 里的 MINIO_HOST/MINIO_PORT 会被展开为 APPFLOWY_S3_MINIO_URL=http://minio:9000，Compose 内服务名即主机名。

3.3 修改参数并使其生效（闭环实测）

修改 .env 后，必须重建对应服务容器才会生效（Compose 只在创建容器时注入环境变量）。以 APPFLOWY_ACCESS_CONTROL 为例做一次完整闭环：

第一步，修改 .env：

sed -i "s/^APPFLOWY_ACCESS_CONTROL=true/APPFLOWY_ACCESS_CONTROL=false/" .env
grep "^APPFLOWY_ACCESS_CONTROL" .env

实测回显：

APPFLOWY_ACCESS_CONTROL=false

第二步，重建服务：

docker compose up -d appflowy_cloud

第三步，验证进程内新值：

docker compose exec appflowy_cloud env | grep "^APPFLOWY_ACCESS_CONTROL="

实测回显：

APPFLOWY_ACCESS_CONTROL=false

第四步，还原为 true 并再次 docker compose up -d appflowy_cloud，docker compose ps appflowy_cloud 确认容器以新配置重建且恢复 healthy：

appflowy-01910-stack-appflowy_cloud-1   appflowyinc/appflowy_cloud:0.19.10   "appflowy_cloud"   appflowy_cloud   6 seconds ago   Up 6 seconds (health: starting)   8000/tcp

💡 源码部署形态（systemd + EnvironmentFile）的等价操作是 systemctl restart appflowy-cloud，无需重建容器。

3.4 未定义变量的告警行为

官方 compose 中部分变量在模板 .env 里被注释或留空，执行任何 docker compose 命令时都会出现告警（实测节选）：

time="2026-10-22T17:28:51Z" level=warning msg="The \"APPFLOWY_S3_REGION\" variable is not set. Defaulting to a blank string."
time="2026-10-22T17:28:51Z" level=warning msg="The \"AZURE_OPENAI_API_KEY\" variable is not set. Defaulting to a blank string."
time="2026-10-22T17:28:51Z" level=warning msg="The \"AZURE_OPENAI_ENDPOINT\" variable is not set. Defaulting to a blank string."
time="2026-10-22T17:28:51Z" level=warning msg="The \"AZURE_OPENAI_API_VERSION\" variable is not set. Defaulting to a blank string."

这些告警无害：APPFLOWY_S3_REGION 仅在使用 AWS S3（APPFLOWY_S3_USE_MINIO=false）时需要；Azure OpenAI 三项仅在 Azure 托管模型场景需要。若希望消除告警，在 .env 中为这些变量显式赋空值即可（如 APPFLOWY_S3_REGION=）。

四、参数总览

AppFlowy Cloud 0.19.10 的 .env 参数按组件分为 9 组，前缀规律清晰：

五、核心参数分类详解

5.1 基础地址参数

⚠️ 桌面客户端配置服务器地址时填的就是 APPFLOWY_BASE_URL 对应的值；若该项与实际访问域名不一致，会出现登录成功但文档列表加载失败的现象。

5.2 PostgreSQL 参数（含 pgvector 依赖链）

数据库依赖链要点（部署排障高频）：

1. pgvector 扩展必须存在——AppFlowy 的语义检索依赖 vector 扩展，官方镜像 pgvector/pgvector:pg16 已内置；自装 PostgreSQL 需安装 postgresql-16-pgvector 包。实测扩展清单（select extname, extversion from pg_extension;）：

 pgcrypto  | 1.3
 plpgsql   | 1.0
 uuid-ossp | 1.1
 vector    | 0.8.7

2. auth 模式：gotrue 以 search_path=auth 连接，其全部表（users、refresh_tokens、schema_migrations 等）在 auth 模式下创建；若模式不存在，gotrue 启动会报 no schema has been selected to create in (SQLSTATE 3F000)（官方镜像会自建，源码部署需先 CREATE SCHEMA IF NOT EXISTS auth AUTHORIZATION postgres;）。
3. 应用侧迁移自动执行：appflowy_cloud 启动时自动运行内嵌的 sqlx 迁移（建 af_user、af_workspace 等业务表），无需手动导入 SQL。
4. 密码特殊字符：密码含 @ : / ? 等字符时必须做 URL 编码后写入连接串（如 p@ss → p%40ss），这是官方注释中明确强调的一点。

5.3 Redis 参数

Redis 8.x 默认无口令即可工作；生产建议开启 requirepass 并把 URI 写成 redis://:PASSWORD@host:6379 形态。

5.4 认证 GoTrue 参数

💡 管理员账号与业务用户是两套体系：admin@example.com 仅用于 /console 管理后台；普通用户通过客户端或 POST /gotrue/signup 注册，落在同一 auth.users 表但无管理员角色。

5.5 对象存储参数

对象存储选型说明（2026-10 实况）：MinIO 社区版已于 2025-10 起停止分发（官方下载返回 410 Gone，Docker Hub 拉取 minio/minio 报 pull access denied），新部署建议直接使用任意 S3 兼容存储并保持 APPFLOWY_S3_USE_MINIO=true（协议层面等价），或将 APPFLOWY_S3_USE_MINIO 设为 false 直连 AWS S3。使用兼容存储时预签名 URL 的 Host 头需与签名端点一致，nginx 的 /minio-api/ 转发里已做对应处理。

5.6 AI 参数（可选）

5.7 后台任务参数

5.8 日志与运维参数

六、生产配置模板（8C16G / SSD，50 人团队场景）

以下为一份实测可用的生产基线模板（适用于 8 核 16GB 内存、SSD 磁盘、50 人以内团队自托管），敏感值务必替换：

# —— 基础 ——
FQDN=flowy.example.com
SCHEME=https
WS_SCHEME=wss
APPFLOWY_BASE_URL=https://flowy.example.com
APPFLOWY_WEBSOCKET_BASE_URL=wss://flowy.example.com/ws/v2

# —— 数据库（建议独立 PostgreSQL 16 + pgvector 实例）——
POSTGRES_HOST=127.0.0.1
POSTGRES_PORT=5432
POSTGRES_USER=appflowy
POSTGRES_PASSWORD=<强口令A>
POSTGRES_DB=appflowy
APPFLOWY_DATABASE_URL=postgres://appflowy:<强口令A>@127.0.0.1:5432/appflowy
GOTRUE_DATABASE_URL=postgres://appflowy:<强口令A>@127.0.0.1:5432/appflowy?search_path=auth
APPFLOWY_DATABASE_MAX_CONNECTIONS=40

# —— 缓存 ——
APPFLOWY_REDIS_URI=redis://:<强口令B>@127.0.0.1:6379

# —— 认证 ——
GOTRUE_JWT_SECRET=<64 位随机串>
GOTRUE_JWT_EXP=604800
GOTRUE_ADMIN_EMAIL=admin@example.com
GOTRUE_ADMIN_PASSWORD=<强口令C>
API_EXTERNAL_URL=https://flowy.example.com/gotrue
GOTRUE_MAILER_AUTOCONFIRM=false
GOTRUE_SMTP_HOST=smtp.example.com
GOTRUE_SMTP_PORT=465
GOTRUE_SMTP_USER=noreply@example.com
GOTRUE_SMTP_PASS=<SMTP口令>
GOTRUE_SMTP_ADMIN_EMAIL=it@example.com
GOTRUE_DISABLE_SIGNUP=false

# —— 对象存储 ——
APPFLOWY_S3_USE_MINIO=true
APPFLOWY_S3_CREATE_BUCKET=false
APPFLOWY_S3_MINIO_URL=http://127.0.0.1:9000
AWS_ACCESS_KEY=<S3-AK>
AWS_SECRET=<S3-SK>
APPFLOWY_S3_BUCKET=appflowy
APPFLOWY_S3_PRESIGNED_URL_ENDPOINT=https://flowy.example.com/minio-api

# —— 后台与日志 ——
APPFLOWY_INDEXER_ENABLED=true
RUST_LOG=info
NGINX_PORT=443

要点说明：CREATE_BUCKET=false 要求建桶动作提前完成（权限收敛到部署流程）；AUTOCONFIRM=false + SMTP 组合让邮箱验证真实生效；TLS 场景三个 SCHEME 必须同步改，否则客户端会出现「能登录不能同步」。

七、常见问题

Q1：修改了 .env 为什么不生效？ Compose 只在容器创建时注入环境变量。执行 docker compose up -d <服务名> 重建对应服务（可多服务一起重建），再用 docker compose exec <服务名> env 核对（见 3.3 实测闭环）。源码部署形态对应 systemctl restart <服务名>。

Q2：docker compose 执行时刷 variable is not set 告警正常吗？ 正常，属于模板中留空的可选变量（APPFLOWY_S3_REGION、Azure OpenAI 三项等），回退为空串不影响运行（见 3.4 实测）。介意的话在 .env 显式赋空值。

Q3：数据库密码含特殊字符导致服务起不来？ 连接串中的特殊字符必须 URL 编码：@→%40、:→%3A、/→%2F。只改 POSTGRES_PASSWORD 不够，所有内嵌连接串（APPFLOWY_DATABASE_URL、GOTRUE_DATABASE_URL、AI_DATABASE_URL、APPFLOWY_WORKER_DATABASE_URL 等）都要同步编码。

Q4：gotrue 启动报 no schema has been selected to create in (SQLSTATE 3F000)？ auth 模式缺失。官方 Compose 镜像会自建；自装 PostgreSQL（源码部署）需先执行 CREATE SCHEMA IF NOT EXISTS auth AUTHORIZATION postgres; 再启动 gotrue（实测该错误与修复过程见《Ubuntu 22.04 安装 AppFlowy 0.19.10 指南》）。

Q5：/console 管理台用 admin@example.com 登录被拒？ 确认三点：gotrue 已完成启动（/gotrue/health 返回 JSON）；管理员账号确实已创建（auth.users 中 role=supabase_admin）；GOTRUE_JWT_SECRET 在 gotrue 与 appflowy_cloud 两侧一致。源码部署形态新版 gotrue 需用 gotrue admin createuser <邮箱> <口令> supabase_admin 显式创建并赋予角色。

Q6：客户端能登录但看不到文档列表 / 无法上传附件？ 逐项核对 APPFLOWY_BASE_URL（与实际访问地址一致）、APPFLOWY_S3_PRESIGNED_URL_ENDPOINT（指向对外可达的 /minio-api 通道）、nginx /ws 与 /api 转发。对象存储凭证错误的表现是登录正常而附件上传持续失败。

Q7：第二个用户注册后报 code 1120「Seat limit reached」？ 0.19.10 官方镜像内置席位管控：未录入商业许可时全实例最多 1 个 Member/Owner（实测第二个用户 /api/user/verify/{token} 返回 {"code":1120,"message":"Seat limit reached: ... (limit 1)."}）。许可状态存于数据库表 af_self_host_commercial_license（实测结构：host / signature / license_id），通过管理台录入有效许可后解除限制。

八、参考链接

• AppFlowy Cloud 官方配置模板：https://github.com/AppFlowy-IO/AppFlowy-Cloud/blob/main/deploy.env
• AppFlowy Cloud 部署文档：https://github.com/AppFlowy-IO/AppFlowy-Cloud/blob/main/doc/GUIDE.md
• GoTrue（supabase/auth）配置参考：https://github.com/supabase/auth
• 站内同系列：《AppFlowy 0.19.10 介绍与选型指南》《AppFlowy 0.19.10 Docker Compose 部署指南》《Ubuntu 22.04 安装 AppFlowy 0.19.10 指南》《AppFlowy 0.19.10 API 使用详解》