入门指南
ComPDF Self-hosted 是基于 Docker Compose 的私有化 PDF 处理平台。当前应用在 8080 端口统一提供 ComPDF Web、Dashboard 和 /api/v1 API。
环境要求
- 64 位 Linux 服务器或 Docker Desktop 环境。
- 至少 4 GB RAM。
- Docker Engine 和 Docker Compose v2。
- 生产使用需要有效的 ComPDF License Key。
快速开始
bash
git clone https://github.com/ComPDFKit/compdf-self-hosted.git
cd compdf-self-hosted
cp .env.example .env
docker compose up -d启动后打开：
| 入口 | URL |
|---|---|
| ComPDF Web | http://localhost:8080/ |
| Dashboard | http://localhost:8080/admin |
| 健康检查 | http://localhost:8080/api/v1/status |
如需使用 Enterprise license，请替换 .env 中的 COMPDF_LICENSE_KEY 并重启服务。
Dashboard 控制台
ComPDF Self-hosted 提供统一管理控制台，用于查看 API Key、API 调用情况与 License 状态，并支持操作日志审计、账号管理及系统基础配置等核心功能，可通过 /admin 访问。
- 概览面板：展示 API Key 详情、API 调用统计、License 授权范围及使用状态等信息。
- 操作日志：跟踪、搜索并导出所有操作日志。
- 账号管理：修改管理员用户名或密码。
- 系统设置：配置系统名称、Logo 和主题色。
首次访问时，Dashboard 会引导你创建初始管理员账号。完成初始化后，使用该账号登录即可管理当前部署实例。
API Key
转档、PDF 工具和异步任务接口都需要 x-api-key。可以在 .env 中设置 API_KEY 固定密钥；如果为空，应用首次启动会自动生成并保存到 STORAGE_DIR/.api-key-plaintext，ComPDF Web 和 Dashboard 会自动使用该 Key。
bash
curl -X POST "http://localhost:8080/api/v1/process/pdf/docx" \
-H "x-api-key: your_api_key_here" \
-F "[email protected]"配置项
| 变量 | 默认值 | 说明 |
|---|---|---|
PORT | 8080 | 应用监听端口。 |
JWT_SECRET | change-me-in-prod | Dashboard 管理端会话 JWT 密钥，生产环境需要修改。 |
API_KEY | 空 | 受保护 API 的明文密钥；为空时首次启动自动生成。 |
CORS_ORIGINS | * | 允许的 CORS origin，多个值用英文逗号分隔。 |
COMPDF_TOOLS_ENABLED | false | ComPDF Web 配置开关，只有字面值 true 会开启。 |
DATABASE_HOST / DATABASE_PORT | compdf-infra / 3306 | 应用使用的 MySQL 地址和端口。 |
DATABASE_USER / DATABASE_PASSWORD / DATABASE_NAME | compdfkit / compdfkit-pass-2026 / compdfkit | MySQL 用户名、密码和数据库名。 |
REDIS_HOST / REDIS_PORT | compdf-infra / 6379 | 应用使用的 Redis 地址和端口。 |
LICENSE_TOKEN_PATH | /app/configs/license.jwt | License token 文件路径。 |
COMPDF_LICENSE_KEY | 空 | ComPDF License Key。 |
COMPDF_LICENSE_SECRET | 空 | 可选 License Secret。 |
COMPDF_AI_MODEL | /opt/compdf_sdk/models/documentai.model | Document AI 模型路径。 |
PUBLIC_DIR | /app/public | 生产镜像中的前端静态资源目录。 |
SETTINGS_PATH | /app/configs/settings.yml | Dashboard 系统设置文件路径。 |
STORAGE_DIR | /app/storage | 任务结果和自动生成 API Key 的存储目录。 |
运维命令
bash
docker compose ps
docker compose logs -f compdf-server
docker compose restart compdf-server开发模式
开发环境请以项目仓库 README 为准。常见流程是先启动 Docker Compose 服务，再本地启动 Server 服务和支持热更新的 Web UI。