一、先确认标准正确部署配置（90% 访问失败是配置写错）
正确 Compose（必须满足 4 个关键点）
yaml
version: "3.8"
services:
cups:
image: anujdatar/cups:latest
container_name: anujdatar-cups
restart: unless-stopped
privileged: true # 必开特权
network_mode: host # 必须host，不能bridge！bridge会导致631只能本机访问、AirPrint失效
devices:
- /dev/bus/usb:/dev/bus/usb
- /dev/usb:/dev/usb
- /dev:/dev
volumes:
- /vol1/1000/anujdatar_cups/config:/etc/cups
- /vol1/1000/anujdatar_cups/spool:/var/spool/cups
- /var/run/dbus:/var/run/dbus
- /etc/avahi/services:/etc/avahi/services
environment:
- CUPSADMIN=admin
- CUPSPASSWORD=admin
- TZ=Asia/Shanghai
致命错误配置（直接导致无法访问后台）
- 用
ports: "631:631"+network_mode: bridgeCUPS 默认只监听本地 127.0.0.1，bridge 映射端口外部浏览器无法访问，同时 AirPrint 完全失效
- 没开
privileged: true权限不足，cupsd 无法绑定 631 特权端口 - 未挂载
/var/run/dbus，cups 进程启动异常 - fnOS 宿主机自带 cups 占用 631 端口
二、分步排查（按顺序操作，SSH 登录 root 执行）
步骤 1：关闭 fnOS 系统自带 CUPS（最高发问题）
宿主机 cups 占用 631，容器 cups 无法绑定端口，直接访问超时 / 拒绝连接
sudo -i
# 停止服务
systemctl stop cups
systemctl stop cups-browsed
# 禁止开机自启
systemctl disable cups
systemctl disable cups-browsed
# 验证631是否释放
ss -tulpn | grep :631
执行后无输出 = 端口释放成功；若还有输出，杀掉占用进程：
lsof -i :631 | awk '{print $2}' | xargs kill -9
步骤 2：检查容器是否正常运行
# 查看容器状态
docker ps | grep anujdatar-cups
- 无输出：容器未启动，去 Docker 面板启动；查看容器日志找报错
docker logs anujdatar-cups
- 状态 Exited：启动失败，日志常见报错：
permission denied bind 631：没开 privileged / 端口被占用- dbus 挂载缺失：补
/var/run/dbus挂载
步骤 3：进入容器内部，验证 cups 服务是否监听 631
# 进入容器终端
docker exec -it --user root anujdatar-cups bash
# 容器内查看端口监听
ss -tulpn | grep 631
两种异常情况
- 无任何 631 输出：cupsd 未启动
容器内重启 cups：
service cups restart - 仅监听 127.0.0.1:631（只允许容器本地访问，外部浏览器打不开）
anujdatar/cups 默认配置限制局域网访问，修改 cupsd.conf 放行所有 IP：
nano /etc/cups/cupsd.conf修改三处：
confListen 0.0.0.0:631 # 替换原来 Listen 127.0.0.1:631 Allow @LOCAL # 局域网全部放行 <Location /> Allow @LOCAL </Location> <Location /admin> Allow @LOCAL </Location> <Location /admin/conf> Allow @LOCAL </Location>保存退出，重启 cups：
service cups restart
步骤 4：浏览器访问方式错误（跳转 https / 连接中断）
anujdatar/cups 默认开启加密，直接输 http 会跳转 https，部分浏览器拦截自签名证书
- 优先使用标准地址：
plaintext
http://NAS_IP:631 https://NAS_IP:631 - Edge/Chrome 提示 “不安全、连接终止” 解决：
- 页面输入
thisisunsafe忽略证书风险进入 - 换 Firefox、夸克浏览器访问，兼容性更好
- 页面输入
- 不要加
/admin直接访问，先进首页再点 Administration
步骤 5：fnOS 防火墙拦截 631 端口
飞牛 OS 内置防火墙阻止局域网访问 631
控制面板 → 网络 → 防火墙 → 放行 TCP 631 端口，保存
步骤 6：网络模式错误（bridge 必踩坑）
如果你用了
network_mode: bridge + 端口映射 631:631，必须改成 host- bridge 模式下 cups 仅监听容器内网 127.0.0.1，宿主机外部无法访问
- host 模式直接复用宿主机网卡，0.0.0.0 监听全局域网，AirPrint 才能正常广播
步骤 7：权限缺失导致 cups 无法启动
- Compose 必须写
privileged: true - 设备映射完整：
/dev/bus/usb /dev/usb /dev - 挂载
/var/run/dbus缺一不可，缺少 dbus cupsd 启动失败
三、一键重置修复命令（全部配置正确仍无法访问时用）
sudo -i
# 停止并删除旧容器
docker stop anujdatar-cups
docker rm anujdatar-cups
# 彻底关闭宿主机cups
systemctl stop cups cups-browsed
systemctl disable cups cups-browsed
# 全新标准host网络启动
docker run -d \
--name anujdatar-cups \
--restart unless-stopped \
--privileged \
--net=host \
-v /dev/bus/usb:/dev/bus/usb \
-v /dev/usb:/dev/usb \
-v /dev:/dev \
-v /var/run/dbus:/var/run/dbus \
-v /etc/avahi/services:/etc/avahi/services \
-v /vol1/1000/anujdatar_cups/config:/etc/cups \
-v /vol1/1000/anujdatar_cups/spool:/var/spool/cups \
-e CUPSADMIN=printadmin \
-e CUPSPASSWORD=Print@2026 \
-e TZ=Asia/Shanghai \
anujdatar/cups
等待 30 秒后访问
http://NASIP:631四、常见报错对应解决方案
-
浏览器：无法访问此网站 / 连接被拒绝
- 宿主机 631 端口占用 → 关闭系统 cups
- 容器未 host 网络、bridge 模式 → 改为 network_mode:host
- 容器未启动，查看 docker logs 报错
-
Upgrade Required 强制跳转 https，页面打不开
访问
https://NASIP:631，页面输入thisisunsafe跳过证书警告 -
打开 631 首页正常，点 Administration 提示 403 Forbidden
cupsd.conf 未放行局域网，进入容器修改 Allow @LOCAL，重启 cups
-
容器启动几秒自动退出（Exited）
- 缺少 privileged 特权
- 未挂载 /var/run/dbus
- config 目录权限损坏，删除
/vol1/1000/anujdatar_cups/config重建
-
能访问 631，但登录账号密码错误
环境变量
CUPSADMIN/CUPSPASSWORD修改后必须重建容器，仅重启不生效
五、验证访问成功标准
- 浏览器打开
http://NASIP:631正常显示 CUPS 首页 - 点击 Administration，输入环境变量账号密码可正常登录
- Add Printer 下拉能识别 USB 打印机
- iPhone/Mac 可自动搜到 AirPrint 打印机
