directus 在 linux 上需通过 npm 或 docker 启动，不可传统安装；npm 方式需 node.js v18.17+、初始化项目、配置 .env（必填 admin_email、admin_password、token_secret）后运行 npm run start；docker 方式推荐生产环境，须显式传入数据库环境变量并确保 sqlite 文件可写或 postgresql 数据库已手动创建。
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 文件。
Zynq‑7000 / Zynq UltraScale+ 硬件调试技能。适用于 Xilinx Zynq（Cortex‑A9/A53 + FPGA）Linux 环境，调试 I2C、I2S、UART、GPIO 等外设。包括设备树配置、内核驱动、用户空间调试工具、交叉编译和常见问题排查，支持 PetaLinux 开发。
- 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 则依赖第一次启动时的文件可写权限。这两点卡住的人最多，但错误日志里几乎不体现。
