常见问题
版本与兼容性
如何确认部署版本? GET /v1/health/version 返回稳定版本号,2.6.0 部署返回 2.6.0。
SDK 请求报响应格式不匹配? Agentbase 自研 SDK 的客户端应发送 X-AppBase-SDK: true,并让 X-Appwrite-Response-Format 匹配当前服务端响应 SemVer(2.6.0 部署为 2.6.0);官方 Appwrite SDK 使用独立兼容上限(默认最高 1.9.0)。严格模式下不匹配的请求被拒,宽松模式仅在响应头 X-Appwrite-Warning 提示。具体行为以部署环境变量为准。
能力不可用
**页面或接口返回 412?** 412 是 capability 语义:该能力在当前部署未启用(如知识库可选索引能力未部署)。先确认部署 capability,再联系平台管理员;这与「用户在项目设置中关闭服务」是两类状态。
侧栏看不到 AI Gateway / Messaging / Sites 入口?
- AI Gateway(统一 AI 网关):项目服务默认关闭,需在项目 Settings 中开启且具备相应权限(见项目总览)。
- Messaging:入口默认不在侧栏显示,经直达 URL
/console/project-{region}-{project}/messaging访问(见界面与路由速查)。 - Sites:依赖部署环境变量
_APP_SITES_ENABLED,实例未开启时不显示。
数据库备份入口消失或显示升级? 备份为 Cloud 付费套餐能力,自托管不显示可用入口;备份策略与恢复操作见数据库。
账号与登录
登录后跳转 MFA 或邮箱验证页? 属正常守卫流:未验证邮箱 → /console/verify-email,启用 MFA → /console/mfa。见注册与登录与组织与账号中心的 MFA 与恢复码小节。
Function 执行报身份不满足安全条件? Function / Site 以受限身份运行,不满足受限身份安全条件时直接失败,不回退为高权限执行;请调整运行配置或部署方式(见函数)。