一、文件关键点说明（你写的配置亮点 + 风险点）
亮点
network_mode: host容器共享宿主机网卡，无需端口映射，AirPrint/avahi 局域网广播百分百正常，解决 bridge 模式苹果设备搜不到打印机的通病，家用打印首选。
- 多设备直通
/dev/bus/usb/dev/usb/dev最大限度兼容各类 USB 打印机、热插拔识别更稳定。
- 分离持久化目录
/etc/cups：打印后台配置、打印机参数/var/spool/cups：打印队列缓存，分离存放避免配置目录臃肿
- 挂载宿主机 dbus + avahi 服务目录，局域网设备发现能力拉满
存在风险 / 冗余项
devices: - /dev:/dev权限过大完整直通宿主机所有硬件，存在安全隐患，日常打印仅保留
/dev/bus/usb足够，可删除/dev:/dev- 账号变量名称错误
ydkn/cups 镜像识别环境变量为
CUPS_ADMIN_USER/CUPS_ADMIN_PASSWORD，你写的CUPSADMIN/CUPSPASSWORD不生效，后台无法用该账号登录管理页 - 挂载
/etc/avahi/services存在冲突风险host 网络模式下容器自带 avahi，挂载宿主机 avahi 目录容易出现广播冲突、重复打印机设备
- 未限制日志持久化，容器日志默认存在容器内，不利于排查故障
二、修正后完整版 docker-compose.yml（可直接复制使用）
yaml
version: "3.8"
services:
cups:
image: ydkn/cups:latest
container_name: ydkn-cups
restart: unless-stopped
privileged: true
# host网络，无需ports映射，AirPrint正常
network_mode: host
# USB打印机必需设备挂载，移除危险全/dev直通
devices:
- /dev/bus/usb:/dev/bus/usb
- /dev/usb:/dev/usb
volumes:
# CUPS配置持久化
- /vol1/1000/ydkn_cups/config:/etc/cups
# 打印任务队列
- /vol1/1000/ydkn_cups/spool:/var/spool/cups
# DBus 局域网设备发现必备
- /var/run/dbus:/var/run/dbus
# 日志持久化（新增，方便排错）
- /vol1/1000/ydkn_cups/logs:/var/log/cups
environment:
# 镜像标准识别变量，修正原变量名错误
- CUPS_ADMIN_USER=admin
- CUPS_ADMIN_PASSWORD=admin
- TZ=Asia/Shanghai
三、fnOS 部署操作步骤
- 提前创建存储目录（SSH 执行）
mkdir -p /vol1/1000/ydkn_cups/{config,spool,logs}
- 在
/vol1/1000/ydkn_cups/新建docker-compose.yml，粘贴上面修正后的配置 - 启动容器
cd /vol1/1000/ydkn_cups
docker-compose up -d
- 查看运行日志，确认无报错
docker-compose logs -f ydkn-cups
四、访问 CUPS 管理面板
host 网络模式无需端口映射，直接访问：
plaintext
http://fnOS本机IP:631
https://fnOS本机IP:631
登录账号：
admin / admin五、关键使用注意事项
- 虚拟机 fnOS 慎用
即使 host 网络，虚拟化 USB 直通给容器依然极易识别失败，虚拟机环境推荐系统原生 CUPS。
- host 模式端口占用说明
宿主机 631 端口不能被其他服务占用（如系统原生 cups），若已装系统 cups，先停止：
sudo systemctl stop cups sudo systemctl disable cups - AirPrint 失效排查
- 确认挂载
/var/run/dbus - 使用
network_mode: host（不要 bridge） - 重启容器：
docker-compose restart cups
- 确认挂载
- 权限优化建议
密码不要使用简单
admin，修改环境变量CUPS_ADMIN_PASSWORD为复杂密码，避免内网被未授权访问打印服务。 - 备份方案
直接备份
/vol1/1000/ydkn_cups整个文件夹，更换 NAS、重装系统后直接复用该目录启动容器，打印机配置完全保留。
六、常用运维命令
# 重启打印服务
docker-compose restart
# 停止并删除容器（配置文件保留）
docker-compose down
# 更新镜像版本
docker-compose pull && docker-compose up -d
