InvoiceShelf 介绍与选型指南

目标：一文讲清 InvoiceShelf 是什么、能解决什么问题、技术架构与功能全貌，并给出与 Invoice Ninja、InvoicePlane、Crater 的量化选型对比。本文为认知与选型篇，全部数据来自官方仓库、官网与文档站联网取证，取证日期 2026-10-24，未做本地实测；部署与命令实测见本专栏后续篇章。

一、环境信息

本文为联网溯源的认知篇，取证环境与来源如下：

• 取证日期：2026-10-24（版本号、星数、许可等数据均以该日查询为准，后续以官方渠道最新值为准）
• 官方网站：invoiceshelf.com
• 官方文档站：docs.invoiceshelf.com（安装、功能指南、迁移、翻译）
• 官方 API 文档站：api-docs.invoiceshelf.com（Swagger UI + OpenAPI 规范）
• 代码仓库：github.com/InvoiceShelf/InvoiceShelf（主仓库）、github.com/InvoiceShelf/docker（生产镜像与 Compose 示例）
• 社区支持：官方 Discord（discord.gg/eHXf4zWhsR）、Crowdin 翻译平台
• 星数与活跃度取证方式：shields.io GitHub 徽章接口与 GitHub Releases Atom 流（GitHub API 直连受限时的取证替代路径）

二、软件概述

InvoiceShelf 是一款免费开源、可自托管（self-hosted）的 Web 开票与收款管理应用，官方一句话定位是「Open Source Invoicing Solution for Individuals & Businesses」（面向个人与企业的开源开票解决方案）。它覆盖从报价（estimate）到发票（invoice）、收款（payment）、费用（expense）记录的完整资金链路，并把客户资料、税制、多币种、周期性账单都保留在用户自己的服务器上，强调「No seats, no SaaS bill, no vendor lock-in」（无席位费、无 SaaS 账单、无供应商锁定）。

InvoiceShelf 的出身值得单独说明：它是已归档项目 Crater（github.com/crater-invoice/crater）的社区延续分支。Crater 曾经是自托管开票领域 star 数最高的项目之一（8.4k stars，shields.io 2026-10-24 取证），但自 2022 年 3 月发布 6.0.6 版后停止维护并归档。InvoiceShelf 承接了 Crater 的 Laravel + Vue 技术栈与 REST API 体系（/api/v1），在其基础上持续发布 2.x 稳定版并开发 3.x 新大版本。对老 Crater 用户而言，InvoiceShelf 提供了官方迁移指南（docs.invoiceshelf.com/migration-guide.html），是事实上的官方升级路径。

版本节奏与维护承诺（官方仓库 README 与 Releases，2026-10-24 取证）：

2.4.7 是一个需要重点说明的安全版本：2026-10-21 官方公告要求所有用户升级，原因是 PHP 语言层修复了 CVE-2026-109618 与 CVE-2026-109619——两个可在未登录状态下远程代码执行的漏洞。官方 Docker 镜像 2.4.6 及以前基于受影响的 PHP 8.4.25，2.4.7 起升级到 PHP 8.4.27。这一事件也印证了自托管财务类应用「及时升级」的重要性。

许可证为 GNU AGPL-3.0（仓库 LICENSE 文件与官网声明），意味着可以免费商用与自托管，但基于它的网络服务修改版需向使用者开放源码；这与其前身 Crater 的 AGPL-3.0 一脉相承。

三、核心架构

InvoiceShelf 是典型的 Laravel 全栈单体应用，后端 API 与前端 SPA 同仓交付。依据 2.4.7 版本 composer.json（raw.githubusercontent.com，2026-10-24 取证）可以精确还原依赖层：

💡 技术拓展：PDF 生成引擎不止 InvoiceShelf 内置的 dompdf 一种。常见选项对比——

引擎	原理/特点	适用场景
dompdf（内置）	纯 PHP 渲染 HTML/CSS 生成 PDF，零外部依赖	小型部署、无 Docker 外部服务时
Gotenberg	独立服务（基于 Chromium）把 HTML 转成 PDF，还原度高	需要复杂排版、字体、精确分页的生产环境
wkhtmltopdf	老牌 WebKit 渲染引擎，已停止积极维护	存量系统兼容

InvoiceShelf 实际同时内置 dompdf 与 Gotenberg 客户端（gotenberg-php ^2.8），可在后台「PDF 驱动」设置中切换；自托管追求发票排版还原度时推荐加挂 Gotenberg 服务，轻量部署用默认 dompdf 即可。

前端为 Vue 3 单页应用（SPA），与后端通过 /api/v1 REST API 通信，认证同时支持两种形态：管理员/财务端的 Sanctum SPA 会话（Cookie + CSRF），以及面向脚本与集成的 Bearer Token；客户门户（customer portal）则是同一套 API 下的独立路由族（/{company}/customer/*）。

数据层支持 SQLite、MySQL、MariaDB、PostgreSQL 四种数据库。官方 Docker 镜像提供三个 Compose 变体（SQLite / MySQL·MariaDB / PostgreSQL），数据模型以「公司（company）→ 客户/发票/报价/费用/付款」为核心，多公司数据通过 company scope 与 unique_hash 隔离。

💡 技术拓展：自托管开票应用的数据库选型不止一种。常见选项对比——

数据库	特点	适用场景
SQLite	单文件、零运维、随应用目录一起备份	个人/小微企业、单实例部署
MySQL / MariaDB	生态最广、工具链成熟	多用户并发、已有 MySQL 运维体系
PostgreSQL	类型系统严格、JSON 能力强	已有 PG 运维体系或需复杂查询

InvoiceShelf 官方 Docker 默认示例以 SQLite 为最小足迹方案，需要外接数据库服务时提供 MariaDB 与 PostgreSQL 变体；本文系列部署篇以 SQLite 变体实测，三种变体官方均有现成 Compose 文件。

部署形态上，官方推荐 Docker Compose（镜像 invoiceshelf/invoiceshelf，基于 serversideup/php 底座，nginx + PHP-FPM 架构，amd64 与 arm64 双架构），同时支持传统手动安装（下载 ZIP 上传服务器后运行安装向导，需自备 PHP 8.4、Web 服务器与数据库）。镜像内置 Laravel 调度器（scheduler），周期发票生成、逾期标记、报价过期等定时任务无需宿主机 crontab。

四、功能特性

依据官网功能页与文档站导航（docs.invoiceshelf.com，2026-10-24 取证），InvoiceShelf 的功能面可归纳为七个功能域：

1. 发票与报价：品牌化发票与报价单，支持自定义字段、税种、备注；报价可一键转为发票；发票支持部分收款（partial payments）、贷记单（credit note）、克隆与状态流转；文档站提供发票模板（custom-templates）与 PDF 生成专项指南。
2. 周期性账单（recurring invoices）：对固定客户/订阅类收入按频率自动生成重复发票，逾期与过期由内置调度器自动标记。
3. 费用与报表：费用录入与收据上传，销售、税金、逾期余额、利润等报表（reports）；仪表盘实时汇总应收（outstanding）、逾期（overdue）与本月已收。
4. 客户门户（customer portal）：客户凭独立入口查看、下载发票并在线支付，无需创建额外账号体系；门户内含客户自己的发票/报价/付款历史。
5. 在线收款：Stripe Checkout 集成（信用卡在线支付）；支付方式（payment methods）与币种可管理，支持汇率提供方（exchange rate providers）自动换算。
6. 多公司与多币种：一套部署运行多个业务主体，各自独立的品牌、币种与税制；内置时区、日期/时间格式、语言等本地化配置，翻译经 Crowdin 协作维护。
7. 平台能力：自定义字段、备份（含 S3/Dropbox 磁盘）、邮件驱动配置与测试、模块（modules）扩展、AI 助手（MCP 协议）、私有网络部署指引（private networks）。

与同类相比，InvoiceShelf 的功能取舍很清晰：聚焦「开票—收款—费用」闭环，不做完整复式记账（那是 Firefly III、Actual 的领域），也不做 ERP 级库存与采购（那是 Odoo、Dolibarr 的领域）。

五、快速开始（最小可用示例）

以下为官方 Docker 仓库 README 给出的最小启动命令（来源：github.com/InvoiceShelf/docker README，2026-10-24 取证；本系列部署篇已按此路径实测并验证，详见本专栏《InvoiceShelf Docker Compose 部署指南》）：

docker run -d \
    --name=invoiceshelf \
    -v ./invoiceshelf/storage:/var/www/html/storage \
    -v ./invoiceshelf/modules:/var/www/html/Modules \
    -e APP_NAME=InvoiceShelf \
    -e APP_ENV=production \
    -e APP_DEBUG=false \
    -e APP_URL=http://localhost:8090 \
    -e DB_CONNECTION=sqlite \
    -e DB_DATABASE=/var/www/html/storage/app/database.sqlite \
    -e CACHE_STORE=file \
    -e SESSION_DRIVER=file \
    -e SESSION_LIFETIME=240 \
    -e SESSION_DOMAIN=localhost \
    -e SANCTUM_STATEFUL_DOMAINS=localhost:8090 \
    -p 8090:8080 \
    invoiceshelf/invoiceshelf:latest

要点说明：

• 容器内监听 8080（nginx + PHP-FPM），通过 -p 8090:8080 映射到宿主 8090 端口；
• APP_URL、SESSION_DOMAIN、SANCTUM_STATEFUL_DOMAINS 三个值必须与实际访问地址（含端口）一致，否则会出现登录后跳转异常（官方 issue #213 有专述）；
• SQLite 数据库文件位于 /var/www/html/storage/app/database.sqlite，随 storage 目录挂载持久化；
• 首次启动后浏览器访问 http://服务器IP:8090 进入安装向导，按步骤设置语言、数据库、管理员账号（默认种子管理员为 admin@invoiceshelf.com，向导中可修改）与公司信息；
• 生产环境官方更推荐使用 docker 仓库提供的三套 Compose 变体之一（SQLite / MariaDB / PostgreSQL）。

不使用 Docker 的手动安装路径：从 invoiceshelf.com/download 下载 ZIP，上传服务器解压后按 docs.invoiceshelf.com/installation.html 的 Manual Installation 指引完成 PHP 8.4 环境配置与安装向导。

六、适用场景与限制

适用场景：

1. 自由职业者与小微企业的日常开票与收款跟踪——典型替代对象是 SaaS 记账工具的订阅费；
2. 需要「客户自助门户 + 在线支付」但不想为此开发系统的服务型团队；
3. 存量 Crater 用户的升级迁移（官方迁移指南 + 社区延续维护）；
4. 多品牌/多主体经营者的统一开票后台（多公司架构原生支持）；
5. 数据主权敏感场景（财务数据必须留在自有服务器）。

限制与注意：

1. 功能边界：不做复式记账与完整会计（无总账/凭证体系），不做库存与采购管理；需要会计级能力应选 LedgerSMB、Firefly III 或 ERP 类产品；
2. 版本生命周期：2.x 稳定线安全维护至 2027-09-01（官方 README 明确），新特性集中在 3.x；生产部署应关注 3.0 正式版的迁移公告；
3. 3.0.0-alpha.11 等预发布版本明确「不适合生产数据」；
4. PHP 8.4 为硬性运行时要求（2.x 线），老旧发行版自带 PHP 无法直装，建议 Docker 或先升级 PHP；
5. 收款集成以 Stripe Checkout 为主，国内支付渠道（支付宝/微信）无官方集成；
6. 单体架构按公司隔离数据，超大规模（数万级客户、高频开票）缺乏官方基准数据，选型时应自行压测。

七、同类选型对比

选取开源自托管开票赛道三个代表性产品与 InvoiceShelf 的前身 Crater 做量化对比（数据来源与日期：shields.io / GitHub Releases Atom，2026-10-24；许可以各仓库 LICENSE 为准，InvoicePlane 许可以其仓库标注为准）：

关键差异与选型解读：

1. 要「Crater 血统 + 最宽松的自托管自由度」选 InvoiceShelf：AGPL-3.0 允许免费商用，API 与数据模型直接延续 Crater，老用户迁移成本最低；1.9k stars 虽不及对手，但社区延续关系明确、版本节奏健康（2026 年仍有稳定版与安全响应）。
2. 要最大生态与第三方集成选 Invoice Ninja：10k stars、v5.x 多年打磨、支付渠道最全；但 ELv2 许可对「作为服务提供给第三方」有限制，且部分托管特性收费，自托管前应核对许可条款。
3. 要极简、MIT 许可的老牌轻量方案选 InvoicePlane：MIT 许可最宽松，功能聚焦发票本身；技术栈较老、API 有限，适合单币种、低并发的个人使用。
4. 不建议再新部署 Crater：仓库已归档，2022 年后无安全更新，且存在本文第二节所述的 PHP 层 CVE 风险面；存量用户应迁移到 InvoiceShelf。
5. 一句话结论：个人/小微自托管开票，InvoiceShelf 是当前 Crater 系用户与新用户的均衡首选；重度依赖在线支付集成与生态则倾向 Invoice Ninja；极端轻量与 MIT 许可刚需则选 InvoicePlane。

八、参考链接

1. InvoiceShelf 官网：https://invoiceshelf.com
2. GitHub 主仓库：https://github.com/InvoiceShelf/InvoiceShelf
3. Docker 生产镜像仓库：https://github.com/InvoiceShelf/docker
4. 官方文档站（安装/功能指南）：https://docs.invoiceshelf.com
5. API 文档站（Swagger/OpenAPI）：http://api-docs.invoiceshelf.com
6. 2.4.7 安全发布公告（Release Notes）：https://github.com/InvoiceShelf/InvoiceShelf/releases/tag/2.4.7
7. Crater 原仓库（已归档）：https://github.com/crater-invoice/crater
8. Crowdin 翻译项目：https://crowdin.com/project/invoiceshelf

九、本专栏系列阅读

• 部署实战：《InvoiceShelf Docker Compose 部署指南》 —— SQLite 与 MariaDB 双变体从零部署、安装向导与排障实录；
• 配置进阶：《InvoiceShelf 2.4.7 配置参数详解》 —— .env 全参数逐项说明与业务配置层实测；
• 运维工具箱：《InvoiceShelf 2.4.7 常用 CLI 命令与工具详解》 —— artisan 命令体系、备份恢复与调度排障。