Part-DB元器件管理系统
说明：Docker 是官方推荐的部署方式，以下教程假设你有一台 Linux 服务器（Ubuntu 22.04/24.04 或 Debian 11/12），已安装 Docker 和 Docker Compose。Part-DB 官方 Docker 镜像为 jbtronics/part-db1，是基于 Apache + PHP-FPM 的经典稳定选择。另有一个实验性的 FrankenPHP 镜像 partdborg/part-db，性能更好但尚在测试阶段。
步骤一：创建项目目录
mkdir -p /opt/part-db
cd /opt/part-db步骤二：生成 APP_SECRET
Part-DB 要求设置一个唯一的随机密钥，用于加密和会话安全。使用以下命令生成：
openssl rand -hex 32保存输出的 64 位十六进制字符串，下一步会用到。
步骤三：创建 docker-compose.yml
在 /opt/part-db 目录下创建 docker-compose.yml 文件：
yaml
version: '3.3'
services:
partdb:
container_name: partdb
image: jbtronics/part-db1:latest
restart: unless-stopped
ports:
- "8080:80"
volumes:
- ./uploads:/var/www/html/uploads
- ./public_media:/var/www/html/public/media
- ./db:/var/www/html/var/db
environment:
- APP_ENV=docker
- APP_SECRET=你刚才生成的64位字符串
- BASE_CURRENCY=CNY
- INSTANCE_NAME=我的元器件库
- ALLOW_ATTACHMENT_DOWNLOADS=0
- USE_GRAVATAR=0
- DEFAULT_LANG=zh_CN
- DEFAULT_TIMEZONE=Asia/Shanghai关键配置说明：
| 环境变量 | 作用 | 注意事项 |
|---|---|---|
APP_SECRET | 加密密钥 | 必须替换为步骤二生成的随机值 |
BASE_CURRENCY | 基础货币 | 设为 CNY，此值一旦设定无法更改 |
INSTANCE_NAME | 实例名称 | 显示在浏览器标题和页面头部 |
ALLOW_ATTACHMENT_DOWNLOADS | 附件下载 | 设为 0 防止用户通过 URL 下载服务器任意文件，官方标注为潜在安全问题 |
USE_GRAVATAR | 头像服务 | 设为 0 禁用外部 Gravatar |
DEFAULT_LANG | 默认语言 | 设为 zh_CN 启用中文界面 |
DEFAULT_TIMEZONE | 时区 | 设为 Asia/Shanghai |
注意：环境变量值不要加引号，否则引号会被当作值的一部分导致错误。这是官方文档中明确警告的常见问题-4-15。
步骤四：启动容器
docker compose up -d等待容器启动完成（约 30 秒），然后检查状态：
docker compose ps
docker compose logs partdb步骤五：初始化数据库
首次启动后需要创建数据库表结构：
docker exec --user=www-data partdb php bin/console doctrine:migrations:migrate --no-interaction命令执行时会在输出中显示自动生成的管理员密码，请务必记录下来。
提示：你也可以在 docker-compose.yml 中设置 INITIAL_ADMIN_PW 环境变量来预设管理员密码，避免依赖输出信息。
步骤六：访问系统
浏览器打开 http://你的服务器IP:8080。使用以下默认凭据登录：
- 用户名：admin
- 密码：步骤五输出中显示的那个密码
登录后立即修改管理员密码。
后续维护命令
更新到新版本：
cd /opt/part-db
docker compose pull
docker compose up -d
# 执行数据库迁移
docker exec --user=www-data partdb php bin/console doctrine:migrations:migrate --no-interaction查看日志：
docker compose logs -f partdb备份数据：你的所有持久化数据都在 /opt/part-db 目录下的 uploads/、public_media/、db/ 三个子目录中，直接备份整个 /opt/part-db 目录即可。注意 uploads/ 目录除了用户上传的附件外，还会存放数据库自动迁移时的备份文件（位于 .automigration-backup 文件夹下）-4。
数据库选择指南
Part-DB 支持三种数据库，选择建议如下：
| 数据库 | 适用场景 | 优点 | 缺点 |
|---|---|---|---|
| SQLite | 个人、小团队（<5人） | 零配置、文件级备份 | 不支持原生正则搜索、Unicode 限制（µ 和 μ 被视为不同字符） |
| MariaDB 10.7+ | 中小团队（5-50人） | 原生自然排序、性能好 | 需额外配置数据库服务 |
| PostgreSQL | 大型实例、高并发 | 事务性 DDL、性能优秀 | 支持较新，测试不如其他后端充分 |
重要：数据库类型一旦选定无法轻易更改，请根据预期规模谨慎选择。
常见问题速查
问题：忘记管理员密码怎么办？
进入容器重置：
docker exec -it --user=www-data partdb php bin/console partdb:users:set-password admin按提示输入新密码。
问题：想用 MySQL/MariaDB 替代 SQLite？
在 docker-compose.yml 中添加 MariaDB 服务，并设置 DATABASE_URL 环境变量指向数据库连接。注意 serverVersion 参数需根据实际版本填写。
问题：如何启用 HTTPS？
Part-DB 容器本身不处理 TLS。推荐在前面加一层 Nginx 或 Caddy 反向代理，由代理层管理证书。如果使用反向代理，需在环境变量中配置 TRUSTED_PROXIES 和 TRUSTED_HOSTS。
问题：导入 KiCad BOM 失败？
确保 KiCad 导出的 BOM 格式为 CSV，且包含必要的字段。Part-DB 对 KiCad 的 BOM 导入支持在持续完善中，建议使用最新版本。
问题：搜索 µ（微符号）找不到 μ（mu）？
这是 SQLite 的 Unicode 限制所致。如需完整的 Unicode 支持，请使用 MariaDB 或 PostgreSQL。
问题：想要更好的性能？
可以尝试实验性的 FrankenPHP 镜像 partdborg/part-db。该镜像基于 Caddy 和 FrankenPHP 构建，支持 PHP worker 模式，可复用已初始化的 Symfony 内核，初步测试显示请求时间从约 50ms 降低到约 10ms，同时 Caddy 的 TLS 处理也更简便。但该镜像目前标记为实验性，worker 模式尚未经过 Part-DB 的充分测试。