Outline必须通过Node.js 18.17+、PostgreSQL 12+和Redis 6.2+三者协同运行，不支持SQLite或内存数据库，缺一不可。
Outline 不支持 Linux 原生二进制部署，也没有官方 Debian/RPM 包或 systemd 服务模板；它必须通过 Node.js 运行时 + PostgreSQL + Redis 启动，且不兼容 SQLite 或内存数据库。
Outline 安装前必须确认的三个依赖项
Outline 是一个基于 Node.js 的现代知识库系统，不是传统 Wiki（如 MediaWiki、XWiki），它的安装本质是部署一个 Web 应用服务。跳过任一依赖都会在 npm start 或 outline 启动时直接报错：
-
PostgreSQL 12+：Outline 强制要求远程 PostgreSQL 实例，DB_URL必须含postgresql://协议，不接受sqlite://或mysql:// -
Redis 6.2+：用于实时协作、缓存和后台任务队列，REDIS_URL缺失会导致登录失败或页面卡在“Loading…” -
Node.js 18.17+（LTS）：官方明确不支持 Node 20+（截至 v0.79.x），用node -v检查版本；Ubuntu/Debian 自带的nodejs包通常太旧，需用 NodeSource 源重装
docker-compose.yml 中最容易填错的环境变量
Outline 官方推荐 Docker 部署，但 docker-compose.yml 里几个关键变量名和值格式非常容易出错，导致容器反复重启或 500 错误：
-
URL必须以https://或http://开头，结尾不能带/—— 错写成URL: mywiki.example.com或URL: http://mywiki.example.com/都会让邮件链接、OAuth 回调、Webhook 全部失效 -
SECRET_KEY不能留空或用默认值（如change-me），否则启动时会报Error: SECRET_KEY must be at least 32 characters；建议用openssl rand -base64 48生成 -
JWT_SECRET和SECRET_KEY是两个独立字段，不能复用同一串值；JWT 过期校验依赖它，填错会导致用户登录后立刻被登出 -
COLLABORATION_URL若启用实时协作（默认开启），必须指向同域下的 WebSocket 地址，例如wss://mywiki.example.com/collab，且 Nginx 需额外配置proxy_set_header Upgrade $http_upgrade;
反向代理配置中常被忽略的 header 转发
Outline 严重依赖客户端真实 IP 和协议信息做安全判断与重定向。如果只配了 proxy_pass http://localhost:3000，会出现：无法登录、头像上传失败、邀请链接跳转到 http://localhost:3000、Webhook 签名验证失败。
Nginx 示例中必须包含以下三项（缺一不可）：
location / {
proxy_pass http://localhost:3000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Port $server_port;
}
其中 X-Forwarded-Proto 决定 Outline 是否启用 HTTPS 重定向；X-Forwarded-For 影响审计日志中的 IP 记录；X-Forwarded-Host 关系到 OAuth 第三方登录回调地址拼接。
初始化管理员账户失败的典型路径问题
Outline 没有 Web 安装向导，首次启动后必须手动创建管理员用户，命令执行位置和参数顺序极易出错：
- 必须在 Outline 项目根目录下运行（即含
package.json和server/的目录），不在该目录下执行会报Cannot find module 'outline' - 命令是
npx outline-cli create-admin --email admin@example.com --name "Admin User"，不是outline create-admin或npm run create-admin - 若提示
Connection refused，先检查DB_URL是否能从该机器psql连上，再确认outline-server是否已npm start并监听中（用lsof -i :3000验证） - 密码不会在命令行中输入，而是由 CLI 自动生成并打印在终端最后一行，形如
Password: abcdefgh12345678—— 这行不复制就再也找不回
Outline 的复杂性不在安装步骤多，而在于每个环节都强耦合——PostgreSQL 字符集不对（必须 utf8）、Redis 密码含特殊字符未 URL 编码、Nginx 缺少某一个 header，都会让整个服务停在某个看似无关的环节。部署时建议逐项验证依赖连通性，而不是等全部配完再测试。
