Linux下Directus安装配置全攻略

本文详解了在Linux系统上部署Directus——一个现代化的开源无头CMS——的两种核心方式（npm本地启动与Docker容器化），强调其本质是Node.js应用，无法传统安装；重点剖析了环境配置的关键陷阱：如必须严格满足Node.js版本、.env中ADMIN_EMAIL/ADMIN_PASSWORD/TOKEN_SECRET等必填项缺一不可、SQLite需确保文件可写而PostgreSQL须手动建库、Docker运行时环境变量必须显式传入、Nginx反向代理必须透传X-Forwarded-*头以避免登录跳转404或认证失败，同时揭示了那些日志不报错却导致502/500/空白页的“静默崩溃点”，比如跳过数据库初始化、误配DATABASE_HOST引发的连接混乱、或修改.env后未重启服务。无论你是开发调试还是上线生产，这篇实操指南都能帮你绕开90%的踩坑路径。

Directus 在 Linux 上不能直接“安装”成传统软件，它本质是 Node.js 应用，必须通过 npm 或 docker 启动；跳过构建步骤或忽略 .env 配置会导致启动后 502/500 或登录页空白。

用 npm 启动 Directus（适合开发与轻量生产）

官方已弃用全局 npm install -g directus，必须进项目目录本地安装。核心流程是：初始化项目 → 配置数据库 → 启动服务。

• 确保系统有 Node.js v18.17+ 和 npm v9+（node -v 和 npm -v 验证）
• 新建空目录，运行 npx create-directus-project@latest my-project（自动拉取最新模板）
• 进入目录后，复制 .env.example 为 .env，重点改三项：DATABASE_CLIENT=pg（或 sqlite3）、DATABASE_HOST、DIRECTUS_ADMIN_EMAIL 和 DIRECTUS_ADMIN_PASSWORD
• SQLite 用户可跳过 host/port，但必须确认 DATABASE_FILENAME=./database.sqlite 路径有写权限
• 执行 npm run start —— 不要用 npm run dev 上生产，它带热重载且默认只监听 localhost

用 docker 运行 Directus（推荐生产环境）

Docker 方式隔离性好，但镜像版本和数据库连接配置极易出错。官方 directus/directus:latest 指向的是预编译产物，不包含 CLI 工具，所以初始化数据库必须靠 command 或提前挂载已初始化的 SQLite 文件。

• PostgreSQL 场景下，先确保 PG 容器已运行并允许远程连接（pg_hba.conf 加 host all all 0.0.0.0/0 md5）
• docker run 命令中必须显式传入 -e DATABASE_CLIENT=pg 等变量，环境变量不会从宿主机自动继承
• SQLite 模式更简单：挂载卷到 /directus/database.sqlite，并确保该文件存在且为空（首次启动会自动建表），否则报 SQLITE_CORRUPT
• 反向代理（如 Nginx）必须透传 X-Forwarded-Proto 和 X-Forwarded-For，否则 auth 回调地址生成错误，登录后跳转 404

.env 必配项与常见 500 错误来源

Directus 启动时不会校验所有 .env 字段，但缺失关键项会在首次访问 API 或登录时崩在 knex 层，日志里只显示 error: column "id" does not exist 这类误导信息。

• 必填且易错：DIRECTUS_ADMIN_EMAIL（格式必须含 @）、DIRECTUS_ADMIN_PASSWORD（至少 8 位）、TOKEN_SECRET（任意长随机字符串，漏设则 JWT 签发失败）
• SQLite 用户务必删掉 DATABASE_HOST、DATABASE_PORT、DATABASE_NAME 这三行，留空或注释掉，否则 Directus 仍尝试连 PG
• STORAGE_LOCATIONS 默认是 local，若要启用 S3，必须同时配齐 STORAGE_LOCAL_DRIVER、STORAGE_S3_KEY 等全套，缺一不可
• 修改 .env 后必须重启进程（npm run start 或 docker restart），环境变量不会热加载

Nginx 反向代理的关键 header 设置

没配对 header 时，用户能打开首页，但登录后跳转到 http://localhost:8055（而非你域名），接着爆 404 或 CORS；API 请求也常返回 401 Unauthorized 却无提示。

• 在 location / 块里加：proxy_set_header X-Forwarded-Proto $scheme; 和 proxy_set_header X-Forwarded-Host $host;
• 如果用了子路径（如 /admin/），还需加 proxy_set_header X-Forwarded-Prefix "/admin"; 并在 .env 中设 ROOT_REDIRECT=/admin
• 禁用 proxy_redirect 默认重写，Directus 自身处理路径重定向，Nginx 改写反而破坏 JWT cookie 的 Path 属性
• 上传大文件需同步调大 client_max_body_size 512m;，否则 POST /files 返回 413

最常被跳过的其实是数据库初始化时机——Directus 不会自动创建 PostgreSQL 的 database schema，得手动 CREATE DATABASE；SQLite 则依赖第一次启动时的文件可写权限。这两点卡住的人最多，但错误日志里几乎不体现。

到这里，我们也就讲完了《Linux下Directus安装配置全攻略》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于Linux的知识点！