appwrite 在 linux 上可通过 docker run 一键安装，需 docker ≥20.10，首次启动需 2–5 分钟；必须修改 .env 中 appwrite_host 和 appwrite_domain 为公网 ip 或域名才能外网访问，且不可关闭 appwrite、mariadb、redis 三个核心服务。
Appwrite 在 Linux 上能直接用 docker run 一键安装
Linux 是 Appwrite 官方最优先支持的部署平台，不需要额外编译或依赖管理。只要系统装了 Docker（≥20.10）和 docker-compose（可选但推荐），就能用一条 docker run 命令完成初始化安装。
常见错误现象是执行后访问 @#@#@#@#@#@#@#@#@#@0 显示连接被拒绝，或控制台加载空白——这通常不是安装失败，而是容器还在拉取镜像、初始化数据库、生成 SSL 证书，整个过程在首次启动时可能耗时 2–5 分钟。
- 确保 Docker daemon 正在运行：
sudo systemctl is-active docker应返回active - 不要用
sudo执行安装命令本身；但宿主机的/var/run/docker.sock必须可读写，普通用户需加入docker用户组：sudo usermod -aG docker $USER，然后重新登录终端 - 安装目录（如
$(pwd)/appwrite）不能是 root 权限受限路径（比如/root或某些加密 home 目录），否则容器内进程无法写入配置 - 首次运行会交互式询问端口（默认 80/443）、是否启用 HTTPS、管理员邮箱等，建议全程按回车用默认值，后续可在 Web 控制台或
.env文件里调整
安装后必须改
.env 才能开放外网访问
Appwrite 默认只监听 127.0.0.1，即使你用云服务器部署，本地浏览器能打开，外部网络也连不上——这不是防火墙问题，而是它的 APPWRITE_HOST 和 APPWRITE_DOMAIN 配置没生效。
安装完成后，appwrite 目录下会生成一个 .env 文件。必须手动编辑它：
- 将
APPWRITE_HOST=127.0.0.1改为你的公网 IP 或域名（比如APPWRITE_HOST=192.168.1.100或APPWRITE_HOST=api.example.com） - 同时设置
APPWRITE_DOMAIN与之完全一致（否则 JWT cookie、重定向、WebSocket 连接都会出错） - 如果用反向代理（Nginx/Caddy），还需加
APPWRITE_FORWARDED_SECRET=your-secret并在代理层透传X-Forwarded-*头
改完保存，重启服务：docker-compose -f appwrite/docker-compose.yml down && docker-compose -f appwrite/docker-compose.yml up -d
docker-compose.yml 里哪些服务不能关
Appwrite 的 docker-compose.yml 默认启用了 7 个服务，但实际核心只有 4 个：
-
appwrite：主 API 服务，必须运行 -
appwrite-mariadb：数据库，不能关（哪怕你打算换 PostgreSQL，也要先跑起来初始化结构） -
appwrite-redis：缓存 + 实时事件队列，关掉会导致实时订阅失效、部分后台任务卡住 -
appwrite-influxdb：监控指标存储，可关，不影响功能
其他如 appwrite-clickhouse（分析）、appwrite-meilisearch（搜索）属于按需启用模块，首次部署建议先保持默认，等业务跑稳再裁剪。
注意：不要手动删掉 yml 里的 service 块再重 up —— 安装脚本生成的 yml 是带初始化逻辑的，删了会导致 appwrite 容器反复 crash 并报错 failed to connect to mariadb: no route to host。
首次登录进不去控制台？检查
APPWRITE_PROJECT_ID 和管理员用户状态
安装完成后，浏览器打开 @#@#@#@#@#@#@#@#@#@0，填邮箱密码却提示 “Invalid credentials” 或 “Project not found”，大概率是以下两个原因：
- 安装过程中你跳过了管理员账户创建（比如 Ctrl+C 中断了交互流程），此时数据库里没任何用户。解决方法：进容器执行初始化命令：
docker exec -it appwrite-appwrite-1 sh -c "php /usr/src/code/appwrite/bin/install"，它会重新走一遍引导流程 - 你用 CLI 或 API 创建过项目，但没把生成的
APPWRITE_PROJECT_ID写进前端 SDK 的初始化参数里。Web 控制台本身不依赖这个 ID，但如果你在自己写的前端里调用了client.setProject()却传了错的 ID，就会静默失败
真正容易被忽略的是：Appwrite 的管理员账户和项目是绑定的，不是全局账号。你在安装时创建的管理员，只属于它自动创建的那个默认项目（ID 通常是 6-character 随机串）。如果之后用 CLI 创建了新项目，那个项目默认没有成员，得手动在控制台的 “Users & Permissions” 里加进去。
所以别急着删默认项目——它不仅是入口，还是权限根节点。
