身份认证
转档 API、PDF API 和异步任务 API 都需要 API Key。健康状态接口为公开接口。Dashboard 使用的接口不在本文档中展开。
获取 API Key
| 方式 | 说明 |
|---|---|
配置 API_KEY | 启动前在 .env 中设置 API_KEY。初始化数据库时，ComPDF Self-hosted 会将该值哈希后写入 api_keys 表。客户端请求时使用明文值作为 x-api-key。 |
| 首次启动自动生成 | 如果未设置 API_KEY 且数据库中没有 active key，初始化脚本会生成随机 API Key，并在启动日志中打印一次。 |
| Dashboard 查看 | 进入 /admin 后，可在 API 管理页面查看当前部署的 API Access Key。 |
首次启动自动生成的明文 Key 也会保存到 STORAGE_DIR/.api-key-plaintext，用于 ComPDF Web 自动携带 x-api-key。请将该文件视为敏感信息。
使用 API Key
bash
curl -X POST "http://localhost:8080/api/v1/process/pdf/docx" \
-H "x-api-key: your_api_key_here" \
-F "[email protected]"如果 Key 缺失、无效或已撤销，ComPDF Self-hosted 返回 401 UNAUTHORIZED。