cups-web: Instructions file for Codex

CUPS Web 开发者指南

本文档面向开发者，介绍项目架构、API、开发流程与扩展方式。用户文档请参阅 README.md。

📚 深度文档：原理说明、故障案例与历史决策已移至 docs/，本文件只保留可快速扫读的规则与契约。

📦 项目概述

• 项目定位：基于 CUPS 的 Web 打印管理工具，前后端分离
• 技术栈：Go 1.26（后端）+ Vue 3（前端）+ SQLite（存储）+ IPP（打印协议）
• 部署形态：单二进制（前端 go:embed）连接外部 CUPS；单容器（AIO）Docker 镜像（cupsd + cups-web 同容器，内置 LibreOffice + Java 21 + OFD 转换器 + Ghostscript + 打印驱动生态）
• 仅 Web 镜像：同一 Dockerfile 的 web-runtime 目标，保留文档转换依赖，通过 CUPS_HOST 或 CUPS_SOCKET_PATH 连接外部 CUPS；标签带 -web 后缀，使用 docker-compose.web.yml，不运行 cupsd 或安装驱动/扫描工具。

⚠️ 历史形态提示：仓库曾经是「cups 镜像 + cups-web 镜像」双容器（cups/ 目录），已在合并提交里删除。现在只有根目录的一份 Dockerfile / entrypoint.sh，构建脚本在 scripts/build/、驱动脚本在 scripts/driver/。

🛠️ 技术栈

后端

组件	说明
Go 1.26	见 go.mod
gorilla/mux	HTTP 路由
gorilla/securecookie	会话管理
modernc.org/sqlite	纯 Go SQLite，无 CGO
OpenPrinting/goipp	IPP 协议
rsc.io/pdf + phpdave11/gofpdf	PDF 解析 / 生成
golang.org/x/image/draw	大图下采样（CatmullRom）
golang.org/x/crypto/bcrypt	密码哈希

前端

组件	说明
Vue 3.5 + Vue Router	hash 模式
Vite 7	构建
@nuxt/ui v4 + Tailwind CSS v4	UI / 样式
pdfjs-dist	预览（PDF 生成由后端 /api/convert 负责）
Bun（本地）/ npm（CI + Docker）	包管理。npm 用于覆盖 linux/arm/v7（Bun 不支持 32-bit ARM）

外部依赖

CUPS（IPP 通信）、LibreOffice（Office → PDF）、Java 21 + ofd-converter.jar（OFD → PDF）、Ghostscript（PDF 标准化）、dpkg/apt-get（运行时驱动安装）。

各依赖的坑位说明（LibreOffice 可写 HOME、gs 字体破坏性改造、runtime 无 dpkg-dev）见 docs/architecture.md。

📁 项目结构

cups-web/
├── cmd/server/                    # 后端主程序
│   ├── main.go                    # 入口与路由注册
│   ├── app.go                     # 全局变量
│   ├── bootstrap.go               # 默认 admin 初始化
│   ├── auth_handlers.go           # 登录 / 登出 / session / csrf
│   ├── login_limiter.go           # 登录失败限流
│   ├── admin_handlers.go          # 管理员：用户 / 设置 / 清理
│   ├── user_handlers.go           # /api/me
│   ├── print_handlers.go          # /api/print（主打印入口）
│   ├── print_records_handlers.go  # 打印记录查询 / 下载 / 重打
│   ├── printer_info_handler.go    # 打印机属性查询
│   ├── convert_handler.go         # /api/convert
│   ├── convert_utils.go           # LibreOffice / OFD 转换工具
│   ├── compose_handler.go         # /api/compose（多页拼版）
│   ├── estimate_handler.go        # /api/estimate（预估页数）
│   ├── preview_handler.go         # /api/preview-page（预览兜底：PDF 单页 → PNG）
│   ├── driver_handlers.go         # /api/admin/drivers/* + 后台任务
│   ├── driver_registry.go         # 驱动注册表
│   ├── file_utils.go              # 文件保存 / 类型识别 / 页数
│   ├── pdf_utils.go               # 图片 / 文本 → PDF
│   ├── pdf_compose.go             # 多页拼版
│   ├── pdf_reorder.go             # 页序重排 + 测试
│   ├── watermark.go               # 水印
│   ├── pdf_normalize.go           # PDF 标准化管线
│   ├── fonts.go                   # 中文字体加载
│   ├── maintenance.go             # 后台维护任务
│   └── version.go                 # 构建期版本号
├── internal/
│   ├── auth/session.go            # securecookie 会话 + CSRF
│   ├── middleware/                 # csrf / security 中间件
│   ├── ipp/                       # IPP 客户端 + URI 校验
│   ├── server/static.go           # 静态资源嵌入（SPA fallback）
│   └── store/                     # 数据层（users / prints / settings）
├── frontend/                      # Vue 3 前端（go:embed dist）
├── ofd-converter/                 # Java OFD → PDF
├── scripts/
│   ├── build/install-cups.sh      # 源码编译 CUPS
│   └── driver/                    # 驱动管理命令 + 安装脚本 + capture-debs.sh（apt 钩子）
├── docker-fonts/                  # 构建期字体与 gs/fontconfig 配置
├── entrypoint.sh                  # AIO 容器启动脚本
├── Dockerfile                     # 共享转换依赖 + AIO / 仅 Web 两个目标
├── docker-compose.yml             # 单服务 AIO
├── docker-compose.web.yml         # 仅 Web，连接外部 CUPS
└── Makefile                       # 构建脚本