Appwrite 2.5.0 配置参数详解

本文所有参数行为均在 2026-10-18 于 Appwrite 2.5.0 实测环境逐项验证，修改前后对比的接口回显均为真实输出。参数全集约 220 个，本文按「运行环境 / 域名网络 / Console 控制 / 密钥安全 / 数据库 / 缓存 / 存储 / 函数计算 / 维护统计 / 端口」十组覆盖高频参数，并附速查表；未列出的长尾参数（VCS 代码托管、OAuth 供应商、SMTP 细分项）见官方环境变量总表。

一、环境信息

查看当前生效的关键参数：

grep -E '_APP_ENV=|_APP_EDITION=|_APP_LOCALE=|_APP_DOMAIN=|_APP_DB_ADAPTER=|_APP_STORAGE_LIMIT=|_APP_HTTP_PORT=' .env

实测回显：

_APP_ENV="production"
_APP_EDITION="self-hosted"
_APP_LOCALE="en"
_APP_DOMAIN="localhost"
_APP_DB_ADAPTER="postgresql"
_APP_STORAGE_LIMIT="30000000"
_APP_HTTP_PORT="8102"

二、.env 文件与生效机制

2.1 文件结构

.env 按功能域分组排列，行格式为 KEY="value"（布尔/开关用 enabled/disabled 字符串，非 true/false）。安装器按部署参数预填：--http-port=8102 写入 _APP_HTTP_PORT，--database=postgresql 写入 _APP_DB_ADAPTER 及 _APP_DB_HOST。首次生成时 _APP_OPENSSL_KEY_V1、_APP_NOTIFICATIONS_TRACKING_SECRET、_APP_GEO_SECRET 三个密钥为随机值，每次生成不同，升级重装时必须沿用旧值。

2.2 修改后如何生效

所有变量在服务进程启动时读取，修改 .env 后必须重建 appwrite 服务进程：

docker compose up -d appwrite

实测回显：

 Container appwrite Starting
 Container appwrite Started

约 8～10 秒后 /v1/health 恢复 {"status":"pass"}，新变量即已生效。变量改动会即时反映到接口行为（下文三组实测可证）。个别参数同时影响多个服务（如 _APP_STORAGE_LIMIT 校验发生在 API 进程，_APP_HTTP_PORT 影响网关），需重建对应服务或整个栈。

三、运行环境与系统类

四、域名与 HTTPS 类（含 _APP_OPTIONS_FORCE_HTTPS 实测）

4.1 实测：开启 _APP_OPTIONS_FORCE_HTTPS

把 .env 中 _APP_OPTIONS_FORCE_HTTPS="disabled" 改为 "enabled" 并重建 appwrite 服务后：

curl -s -i http://127.0.0.1:8102/v1/health

实测回显：

HTTP/1.1 301 Moved Permanently
Content-Length: 0
Content-Type: text/html
Date: Sun, 18 Oct 2026 12:22:41 GMT
Location: https://127.0.0.1/v1/health
Server: swoole-http-server

所有 HTTP 请求被 301 到同路径 HTTPS。改回 disabled 重建后恢复正常 API 响应。结论：该开关只控制「是否跳转」，不负责证书——生产开启它的前提是网关已配好 443 证书（_APP_ROUTER_AUTO_CERTIFICATES=enabled 时依赖 _APP_DOMAIN 可解析到本机）。

五、Console 访问控制类（含白名单实测）

5.1 实测：_APP_CONSOLE_WHITELIST_EMAILS

设置 _APP_CONSOLE_WHITELIST_EMAILS="admin@example.com" 并重建服务后，用白名单外邮箱注册 console 账号：

curl -s -X POST http://127.0.0.1:8102/v1/account \
  -H 'X-Appwrite-Project: console' -H 'Content-Type: application/json' \
  -d '{"userId":"unique()","email":"evil@test.com","password":"q1w2e3r4","name":"Evil"}'

实测回显：

{"message":"Console registration is restricted to specific emails. Contact your administrator for more information.","code":401,"type":"user_email_not_whitelisted","version":"2.5.0"}

白名单内但已存在的邮箱（注册请求越过了白名单检查，撞上根管理员数量限制）：

{"message":"Sign up to the console is restricted. You can contact an administrator to update console sign up restrictions by setting _APP_CONSOLE_WHITELIST_ROOT to \"disabled\".","code":501,"type":"user_console_count_exceeded","version":"2.5.0"}

还原白名单为空后，任意邮箱注册同样返回 501 user_console_count_exceeded——_APP_CONSOLE_WHITELIST_ROOT=enabled 时全实例只允许 1 个根管理员。生产建议：ROOT 保持 enabled（单人运维）或 disabled + EMAILS 白名单（团队运维），二选一。

六、密钥与安全类

七、数据库类

实测部署仅启用了 postgresql（安装器按 --database=postgresql 裁剪 compose，MongoDB/MariaDB 服务未纳入栈）。.env 中 DocumentsDB 指向 mongodb 但开关为 disabled，属于预留状态——开启 DocumentsDB 需要补部署 MongoDB 服务并改 compose，不是纯 .env 动作。

八、缓存与队列类

九、存储类（含 _APP_STORAGE_LIMIT 实测）

9.1 实测：_APP_STORAGE_LIMIT 的即时约束

把 _APP_STORAGE_LIMIT 从 30000000 改为 1024 并重建服务后，创建存储桶的 maximumFileSize 立即被压到新限额内：

curl -s -X POST http://127.0.0.1:8102/v1/storage/buckets \
  -H 'X-Appwrite-Project: quzuo-demo' -H "X-Appwrite-Key: <API Key>" \
  -H 'Content-Type: application/json' \
  -d '{"bucketId":"docs","name":"Docs","permissions":["read(\"any\")","create(\"users\")"],"fileSecurity":false,"enabled":true,"maximumFileSize":30000000}'

实测回显（旧值 30000000 直接被拒）：

{"message":"Invalid `maximumFileSize` param: Value must be a valid range between 1 and 1,024","code":400,"type":"general_argument_invalid","version":"2.5.0"}

改用 maximumFileSize=1024 建桶成功后，上传 2KB 文件：

{"message":"File size not allowed","code":400,"type":"storage_invalid_file_size","version":"2.5.0"}

上传 200B 文件成功（节选）：

{"$id":"6ad4bab322e350def298","bucketId":"docs","$createdAt":"2026-10-18T12:25:23.152+00:00","name":"small.bin",...

结论：_APP_STORAGE_LIMIT 同时是「桶最大文件」与「上传请求」的双重天花板，修改即时生效、无需迁移。生产按业务文件尺寸规划，建议 ≥ 100MB（100000000）。

十、函数与计算类

十一、维护与用量统计类

十二、端口与镜像版本类

十三、参数速查表（高频 20 项）

十四、FAQ

14.1 改了 .env 不生效？

变量在进程启动时读取。改完必须重建 appwrite 服务（docker compose up -d appwrite），只 restart 不会重读 env_file（restart 不重新注入环境变量）。判断是否生效：本文三组实测（FORCE_HTTPS 301 / 白名单 401 / 存储限额 400）都是重建后立刻可观测的行为变化，可任选一项做冒烟验证。

14.2 .env 里的引号能去掉吗？

不能随意去。安装器生成统一为 KEY="value" 带引号格式，Compose v2 的 env_file 解析会剥离引号；若混用带空格/特殊字符的值（如 _APP_TRUSTED_PROXIES 的逗号网段），保持引号最稳妥。空值变量写成 _APP_CONSOLE_WHITELIST_EMAILS=（无引号无值）即可，实测还原时如此操作并生效。

14.3 数据库适配器能从中途切换吗？

_APP_DB_ADAPTER 决定数据落在哪，切换等于换数据层：需先导出（REST API 遍历或官方迁移工具），再以新适配器重建部署导入。不要指望改个变量就完成切换。

14.4 哪些变量改动风险最高？

三类：_APP_OPENSSL_KEY_V1（动了全部加密数据失联）、_APP_DB_ADAPTER / _APP_DB_HOST（动了数据去向）、_APP_DOMAIN（动了 Cookie 域与证书签发，全部已登录会话失效）。这三类操作前先备份 postgresql 数据卷与 .env。

14.5 默认密钥必须改吗？

_APP_EXECUTOR_SECRET 与 _APP_JOBS_SECRET 默认 your-secret-key，_APP_DB_PASS 默认 password——内网也建议全改，这些是服务间信任的根。_APP_OPENSSL_KEY_V1 安装器已随机生成，无需手动改。

十五、参考链接

• 官方环境变量总表：https://appwrite.io/docs/advanced/self-hosting/environment-variables
• 官方配置指南：https://appwrite.io/docs/advanced/self-hosting/configuration
• 数据库后端配置：https://appwrite.io/docs/advanced/self-hosting/configuration/databases
• 部署过程与子网规划：《Appwrite Docker Compose 部署指南》
• 参数验证所用接口：《Appwrite 2.5.0 API 使用详解》