Question 1

为什么预定的Appwrite函数在连接到localhost时会出现'connection refused'错误？

Accepted Answer

在自托管的Appwrite 1.9.0中，调度函数可能尝试连接到https://localhost/v1而不是你实际的Appwrite域名，因为调度容器缺少_APP_DOMAIN环境变量。解决方法：编辑你的docker-compose.yml，并向'appwrite-task-scheduler-functions'和'appwrite-task-scheduler-executions'服务添加以下环境变量：_APP_DOMAIN, _APP_DOMAIN_FUNCTIONS, _APP_DOMAIN_SITES, _APP_CONSOLE_DOMAIN, _APP_OPTIONS_FORCE_HTTPS, _APP_MIGRATION_HOST, _APP_CONSOLE_SCHEMA。然后运行'docker compose up -d'来应用。这确保了调度执行使用正确的端点。永久修复是在未来版本中默认传播这些变量。

Question 2

如何修复使用 Cloudflare SMTP 时出现的 Appwrite 邮件超时 "SMTP connect() failed" 错误？

Accepted Answer

这是由 Swoole 的 `SWOOLE_HOOK_SSL` 标志破坏了 Appwrite 邮件 worker 中的 `ssl://` 流所导致的（Swoole 5.1.7 + PHP 8.3.17 + OpenSSL 3.3.3）。连接会停滞 30 秒，然后返回 EOF，因此 PHPMailer 报告 `SMTP connect() failed` / `Called QUIT without being connected`。Appwrite 1.7.x 的临时解决方法：修改两个 worker 文件中的 hook 标志，使其同时排除 `SWOOLE_HOOK_SSL`： ``` MSG= MAIL= # 备份原始文件 docker cp $MSG:/usr/src/code/src/Appwrite/Platform/Workers/Messaging.php ./Messaging.php.bak docker cp $MAIL:/usr/src/code/src/Appwrite/Platform/Workers/Mails.php ./Mails.php.bak # 应用补丁：SWOOLE_HOOK_ALL ^ SWOOLE_HOOK_TCP ^ SWOOLE_HOOK_SSL docker exec $MSG sed -i 's/SWOOLE_HOOK_ALL ^ SWOOLE_HOOK_TCP)/SWOOLE_HOOK_ALL ^ SWOOLE_HOOK_TCP ^ SWOOLE_HOOK_SSL)/' /usr/src/code/src/Appwrite/Platform/Workers/Messaging.php docker exec $MAIL sed -i 's/SWOOLE_HOOK_ALL ^ SWOOLE_HOOK_TCP)/SWOOLE_HOOK_ALL ^ SWOOLE_HOOK_TCP ^ SWOOLE_HOOK_SSL)/' /usr/src/code/src/Appwrite/Platform/Workers/Mails.php docker restart $MSG $MAIL ``` 要还原，使用 `docker cp` 将 .bak 文件复制回容器并重启。注意：这会同时影响 `Messaging.php`（第 96 行）和 `Mails.php`（第 53 行），因此如果不应用此修复，验证邮件和密码找回邮件也会无法发送。根据维护者的说法，由于 Appwrite 已不再使用 PHPMailer，该问题已在 main 分支上修复，因此升级是永久解决方案。

Question 3

如何修复在 Appwrite Sites 上部署 Next.js monorepo 时出现的 "mv: can't rename '/usr/local/build/next.config.*': No such file or directory" 错误？

Accepted Answer

此错误发生在 SSR 打包过程中,当你的 Next.js 应用位于 monorepo 子目录(例如 `./apps/web`)而不是仓库根目录时。Open-runtimes 在构建根目录(`/usr/local/build/`)中查找 `next.config.*`,而不是在应用的子目录中查找。此问题已在 open-runtimes PR #575(open-runtimes/open-runtimes#575)中修复,因此请使用更新后的运行时重新部署你的站点。monorepo 的正确构建设置:将根目录设置为 `./`(以便 bun/npm 解析 workspace 依赖),将输出目录设置为 `./apps/web/.next`,并添加一个构建步骤,在构建 Next.js 应用之前先构建你的 workspace 依赖。

Question 4

如何修复 Appwrite SDK README 在生成后显示错误的服务器版本？

Accepted Answer

横幅被错误地从 --version spec 文件夹名称（例如 1.9.x）中获取，而不是从 spec 实际的 info.version（例如 2.0.0）中获取。此问题已在 PR #14305 中修复：SDKs::getServerVersion() 会解析 info.version 并将其缩减为 major.minor.x，例如 2.0.0 → 2.0.x 和 2.4.3 → 2.4.x。Static-spec SDKs 继续使用 --version。将 SDK 生成器更新到已合并的修复，然后重新生成并发布 SDK。对于已发布的 README，作为临时变通方法，手动更正服务器版本横幅。

Question 5

如何为 Appwrite 用户注册添加 CAPTCHA（reCAPTCHA、hCaptcha、Turnstile）以阻止机器人注册？

Accepted Answer

Appwrite 目前还没有原生的 CAPTCHA 集成（功能请求 #5384 仍处于开放状态）。官方的解决方法是使用 Appwrite Function：

1. 在 Appwrite Console 中进入 Auth > Security，将 'Users Limit' 设置为 1。这会阻止所有客户端的账户创建，使机器人无法直接通过 API 注册。
2. 将 CAPTCHA 小部件（Cloudflare Turnstile、hCaptcha 或 reCAPTCHA）添加到你的客户端注册表单中。
3. 创建一个 Appwrite Function，接收来自客户端的 CAPTCHA token 以及邮箱、密码和姓名。
4. 在函数内部，使用你的 secret key 向提供商的 siteverify 端点（例如 https://challenges.cloudflare.com/turnstile/v0/siteverify 或 https://hcaptcha.com/siteverify）验证该 token。
5. 只有在验证通过时，才使用 Appwrite Server SDK 配合 API key 调用 users.create() 来创建账户；否则拒绝该请求。

注意事项：将 Users Limit 设置为 1 会禁用所有客户端注册，因此首次 OAuth/SSO 登录（同样会创建用户）可能会受到影响，也需要通过函数来处理。

Appwrite

核心功能

避坑指南

适用场景

标签

快速上手

相似推荐