Invoice Ninja 本地部署实战：Docker+FRP 自建开票系统

1. 为什么是 Invoice Ninja？本地部署不是“多此一举”，而是掌控权的起点

Invoice Ninja 这个名字在自由职业者、小型工作室和独立开发者的工具清单里，出现频率高得有点反常——它不像 QuickBooks 那样铺天盖地打广告，也不像 Xero 那样绑定一整套云生态，但它在 GitHub 上常年保持 12k+ Stars，Discord 社区里每天有上百条真实问题在滚动。我第一次接触它，是在帮一位做 UI 设计的朋友搭个人工作台时。她拒绝用任何需要注册邮箱、绑定信用卡、上传客户数据到第三方服务器的开票工具。“我的客户信息、项目报价单、付款记录，凭什么存在别人的数据库里？”这句话让我重新审视了“开票系统”这件事的本质：它从来就不是功能越全越好，而是数据主权越清晰越稳。

Invoice Ninja 的开源属性，恰恰卡在这个痛点上。它的后端是 Laravel，前端是 Vue，整个代码仓库完全公开，你可以 audit 每一行 SQL 查询是否在偷偷上报日志，可以确认邮件模板是否真的只走你配置的 SMTP，甚至能自己加一个“导出为 PDF 并自动水印‘内部使用’”的功能模块。这不是理论上的自由，而是实打实的操作路径。而“本地部署”四个字，就是把这种自由从代码层面，落到你手边这台物理机器或虚拟机上的关键动作。它不等于“只能在自己电脑上打开 http://localhost:8000”，而是指：整个服务栈（Web 服务、数据库、队列、文件存储）全部运行在你可控的环境里，没有中间商，没有默认勾选的分析追踪，没有突然涨价的订阅制陷阱。

至于“实现外部访问”，很多人第一反应是“那不就又变回云服务了吗？”——这是最大的误解。外部访问 ≠ 数据上云。它只是让身处不同网络环境的协作方（比如你的会计、客户、外包设计师）能通过一个稳定域名访问你本地跑着的系统，而所有数据依然躺在你自己的硬盘上。就像你家里的 NAS，开了 DDNS 和端口映射，朋友能远程看照片，但照片从未离开你家的硬盘。这里的关键分水岭在于：流量路径是否经过第三方中转服务器。很多所谓“内网穿透”工具，底层其实是把你的本地端口流量先发到他们的公网服务器，再由对方转发给访问者——这就引入了信任链和性能瓶颈。而真正可控的方案，是用你自己的 VPS 做跳板，或者用可自建的穿透协议（如 FRP 的服务端部署在你租的轻量云上），把控制权牢牢握在自己手里。这也是为什么搜索热词里反复出现 “cpolar 内网穿透”、“frp 内网穿透教程”、“lucky 内网穿透怎么设置”，大家不是在找捷径，而是在找一条不交出数据解释权的合规外网通道。接下来要做的，不是教你怎么点几下鼠标完成部署，而是带你亲手把 Invoice Ninja 的每一层依赖、每一个配置项、每一次网络握手，都变成你脑子里清晰可调的模块。

2. 整体架构设计：为什么必须用 Docker Compose？Nginx 不只是“反向代理”那么简单

2.1 三层隔离结构：Web 层、数据层、接入层的硬性分工

Invoice Ninja 看似只是一个 PHP 应用，但实际运行起来，它至少需要三个独立进程协同工作：PHP-FPM 处理业务逻辑、MySQL 存储所有发票/客户/设置数据、Redis 缓存会话和队列任务。如果直接在宿主机上装 Apache + MySQL + Redis，看似简单，但很快会掉进几个深坑：PHP 版本冲突（系统自带 PHP 7.4，而 Invoice Ninja v6 要求 8.1+）、MySQL 配置被其他服务修改导致开票失败、Redis 密码没设好被扫段端口拖库。我试过三次裸机部署，每次都在上线前一周因为某个依赖版本突兀升级而全线崩溃。后来彻底转向容器化，不是跟风，而是被现实逼出来的。

Docker Compose 就是解决这个问题的“声明式说明书”。它用一个docker-compose.yml文件，把整个服务栈的拓扑关系、资源限制、启动顺序、网络互通规则，全部写死。比如，你明确告诉 Compose：“MySQL 容器叫db，暴露 3306 端口但只允许app容器访问；Redis 叫redis，密码是myredispass；PHP 应用叫app，它必须等db和redis都健康后再启动”。这种“先定义再执行”的模式，让部署不再是靠记忆敲命令，而是靠一份可版本管理、可团队共享、可一键重建的配置文件。更重要的是，它天然实现了环境一致性——你在 Ubuntu 22.04 上测试通过的docker-compose.yml，拿到 macOS 或 Windows Docker Desktop 上，只要 Docker 引擎版本不低于 20.10，就能 100% 复现相同行为。这点对后续维护太关键了：当客户说“你们系统昨天还能开票，今天点提交就白屏”，你不用猜“是不是服务器时间不对”，而是直接docker-compose logs app看 PHP 错误，docker-compose exec db mysql -u root -p invoice_ninja -e "show tables;"验证数据库连通性，三分钟定位到是 Redis 连接超时，而不是花两小时排查系统级防火墙。

2.2 Nginx 的双重角色：静态资源托管 + 安全网关

很多人把 Nginx 当成一个“转发器”，配个proxy_pass http://app:8000;就完事。但在 Invoice Ninja 场景下，它承担着远超转发的职责。首先，Invoice Ninja 的前端资源（Vue 打包后的 JS/CSS/图片）默认是通过 PHP 的public/目录直接输出的，效率极低。而 Nginx 原生支持高效缓存和 Gzip 压缩，能把静态文件响应时间从 300ms 降到 20ms。其次，它是最外层的安全屏障。Invoice Ninja 的.env文件里有数据库密码、API 密钥、加密密钥，这些绝不能被外部直接访问。Nginx 的location ~ /\.env规则，能确保任何人请求https://yourdomain.com/.env都返回 403 Forbidden，而不是把明文密钥吐出来。更关键的是 HTTPS 终止。Let’s Encrypt 的证书必须由 Nginx 加载，它负责解密 HTTPS 流量，再以 HTTP 协议转发给内部的app容器。这意味着app容器根本不需要处理 SSL，专注业务逻辑即可，安全边界清晰。最后，它还是流量整形器。比如你发现客户频繁刷新发票页面导致 CPU 升高，加一条limit_req zone=invoice burst=5 nodelay;就能限制每秒最多 5 次请求，防爬虫也防误操作。这些能力，是 Apache 或 Caddy 在同等配置复杂度下难以兼顾的。

2.3 内网穿透的选型逻辑：为什么避开“即开即用”类工具

搜索热词里高频出现的 “cpolar”、“ngrok”、“lucky”，它们共同特点是：注册账号 → 下载客户端 → 输入认证 token → 启动 → 得到一个xxx.cpolar.io的临时域名。方便是真方便，但隐患也是真隐患。第一，所有流量必须经过 cpolar 的服务器中转，你无法审计其传输加密强度，也无法保证其服务器不被渗透；第二，免费版带宽和并发数严格受限，当客户集中下载月度报表时，连接直接断开；第三，域名不可定制，abc123.cpolar.io这种链接发给客户，专业感归零。所以，我们选择FRP（Fast Reverse Proxy）作为穿透方案，核心理由就一条：服务端（frps）完全由你控制。你可以把它部署在阿里云轻量应用服务器（年付 99 元）、腾讯云 CVM（学生机 10 元/月）、甚至一台闲置的树莓派上。只要这台服务器有固定公网 IP 和开放的端口（比如 7000），你就能建立一条专属隧道。FRP 的配置极其透明：frpc.ini里只写server_addr = your-vps-ip、server_port = 7000、[web]段指定本地127.0.0.1:80映射到远程subdomain = invoice。没有黑盒，没有隐藏收费项，所有日志都在你手里。这才是“实现外部访问”该有的样子——不是租用通道，而是自建桥梁。

3. 核心细节解析：从 Docker 镜像选择到 Nginx 安全加固的实操要点

3.1 镜像源与版本锁定：为什么不用 latest，而选 6.2.0-apache

Invoice Ninja 官方 Docker Hub 仓库（invoiceninja/invoiceninja）提供了多个标签：latest、apache、fpm、6.2.0、6.2.0-apache。新手最容易犯的错，就是无脑拉取latest。我踩过这个坑：某天docker-compose up -d后，登录界面直接报Class 'App\\Console\\Commands\\SetupCommand' not found。查日志发现，latest标签指向的镜像，其 Laravel 框架版本已升级到 10.x，而 Invoice Ninja v6.1 的代码尚未完全兼容。官方文档明确建议生产环境使用语义化版本号，比如6.2.0-apache。这个标签意味着：PHP 8.1.12、Apache 2.4.52、Laravel 9.52.15、所有 Composer 依赖精确锁定。它不会自动更新，除非你手动改docker-compose.yml里的image:行。

另一个关键点是apache和fpm的选择。fpm镜像只包含 PHP-FPM 进程，必须搭配 Nginx 或 Apache 作为 Web 服务器；apache镜像则内置了 Apache + mod_php，开箱即用。对于初学者，apache是更稳妥的选择，因为它省去了 Nginx 与 PHP-FPM 的 socket 通信调试（常见错误：connect() to unix:/var/run/php/php8.1-fpm.sock failed）。但长远看，fpm+ Nginx 组合性能更好、配置更灵活。我们本次采用6.2.0-apache，在docker-compose.yml中这样写：

services: app: image: invoiceninja/invoiceninja:6.2.0-apache restart: always environment: - APP_ENV=production - APP_DEBUG=false - DB_HOST=db - DB_DATABASE=invoice_ninja - DB_USERNAME=root - DB_PASSWORD=your_db_password - REDIS_HOST=redis - REDIS_PASSWORD=your_redis_password - APP_KEY=base64:your_long_random_key_here volumes: - ./storage:/var/www/html/storage - ./bootstrap/cache:/var/www/html/bootstrap/cache

注意volumes的挂载：storage目录存放上传的发票 PDF、客户头像、自定义 Logo，必须持久化，否则容器重启后文件全丢；bootstrap/cache存放 Laravel 的配置缓存，挂载后能避免每次启动都重新生成，提升响应速度。

3.2 MySQL 配置的致命细节：字符集与排序规则必须统一

Invoice Ninja 对数据库字符集要求极为苛刻。如果 MySQL 容器用默认配置（utf8mb4字符集，但utf8mb4_general_ci排序规则），在创建客户时输入中文姓名或日文地址，保存后可能变成乱码，或者搜索时完全匹配不到。根源在于 Laravel 的 Eloquent ORM 默认使用utf8mb4_unicode_ci，它对 emoji 和多语言排序的支持更严谨。因此，MySQL 服务必须显式指定：

db: image: mysql:8.0 restart: always environment: MYSQL_ROOT_PASSWORD: your_root_password MYSQL_DATABASE: invoice_ninja MYSQL_USER: ninja MYSQL_PASSWORD: your_db_password command: --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci volumes: - ./mysql-data:/var/lib/mysql

command行强制覆盖 MySQL 启动参数，确保全局字符集生效。同时，在app容器的.env环境变量中，必须添加：

DB_CHARSET=utf8mb4 DB_COLLATION=utf8mb4_unicode_ci

这两处配置必须严格一致，缺一不可。我曾因漏掉DB_COLLATION这一行，导致客户列表里所有中文名字显示为????，排查了整整一个下午才定位到。

3.3 Nginx 配置的五个安全锚点：从 TLS 到目录遍历防护

Nginx 配置文件（通常放在./nginx/conf.d/invoice.conf）不是简单转发，而是安全防线。以下是必须写死的五条规则：

1. HTTPS 强制重定向：所有 HTTP 请求 301 跳转到 HTTPS。

   server { listen 80; server_name invoice.yourdomain.com; return 301 https://$server_name$request_uri; }

2. TLS 1.2+ 与强加密套件：禁用老旧协议，防止降级攻击。

   ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers 'ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384'; ssl_prefer_server_ciphers off;

3. .env和敏感目录禁止访问：这是最基础的防护。

   location ~ /\.(env|log|ini|conf|git|htaccess|htpasswd) { deny all; } location ~ ^/(vendor|node_modules|storage/app|storage/framework|storage/logs) { deny all; }

4. 防止目录遍历攻击：alias指令必须配合^~前缀，避免正则匹配绕过。

   location ^~ /storage/app/ { alias /var/www/html/storage/app/; internal; # 仅允许内部重定向访问，禁止外部直接请求 }

5. CSP（内容安全策略）头：防止 XSS 注入。

   add_header Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; font-src 'self'; connect-src 'self'; frame-ancestors 'none';" always;

提示：internal;指令是关键。它确保/storage/app/下的文件只能通过 Laravel 的Storage::download()方法触发，而不能被用户直接拼 URL 下载，比如https://invoice.yourdomain.com/storage/app/invoices/2023-001.pdf会返回 404，必须走/download/invoice/123这样的路由。

4. 实操过程：从 Ubuntu 22.04 初始化到 FRP 穿透成功全记录

4.1 环境初始化：Ubuntu 22.04 的最小化安全加固

我们以一台全新的 Ubuntu 22.04 服务器为例（物理机或云服务器均可）。第一步不是装 Docker，而是关掉所有不必要的服务，减少攻击面：

# 更新系统并清理旧包 sudo apt update && sudo apt upgrade -y sudo apt autoremove -y # 禁用 IPv6（除非你明确需要，否则增加复杂度） echo 'net.ipv6.conf.all.disable_ipv6 = 1' | sudo tee -a /etc/sysctl.conf echo 'net.ipv6.conf.default.disable_ipv6 = 1' | sudo tee -a /etc/sysctl.conf sudo sysctl -p # 安装并启用 UFW 防火墙，只开放必要端口 sudo ufw allow OpenSSH sudo ufw allow 80/tcp sudo ufw allow 443/tcp sudo ufw enable

接着安装 Docker 和 Docker Compose。注意：Ubuntu 官方源的docker-compose包已废弃，必须用 Docker 官方脚本安装：

# 安装 Docker Engine sudo apt install ca-certificates curl gnupg lsb-release -y curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null sudo apt update sudo apt install docker-ce docker-ce-cli containerd.io -y # 安装 Docker Compose（v2.20.2，稳定版） sudo curl -L "https://github.com/docker/compose/releases/download/v2.20.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose sudo chmod +x /usr/local/bin/docker-compose

验证安装：

docker --version # 应输出 Docker version 24.0.5, build ced0996 docker-compose --version # 应输出 Docker Compose version v2.20.2

注意：不要用sudo apt install docker-compose，它安装的是已淘汰的 v1 版本，docker-compose ps会报错no configuration file provided: not found。

4.2 构建完整 docker-compose.yml：含健康检查与资源限制

创建项目目录invoice-ninja，进入后编写docker-compose.yml。以下是我经过 12 次迭代后确认的生产级配置，重点在健康检查和资源限制：

version: '3.8' services: # Nginx 反向代理（单独容器，便于证书管理） nginx: image: nginx:alpine restart: always ports: - "80:80" - "443:443" volumes: - ./nginx/conf.d:/etc/nginx/conf.d - ./nginx/ssl:/etc/nginx/ssl - ./nginx/logs:/var/log/nginx - ./storage:/var/www/html/storage # 与 app 容器共享 storage depends_on: - app healthcheck: test: ["CMD", "curl", "-f", "http://localhost:80/health"] interval: 30s timeout: 10s retries: 3 # Invoice Ninja 主应用 app: image: invoiceninja/invoiceninja:6.2.0-apache restart: always environment: - APP_ENV=production - APP_DEBUG=false - APP_URL=https://invoice.yourdomain.com - DB_HOST=db - DB_DATABASE=invoice_ninja - DB_USERNAME=ninja - DB_PASSWORD=your_secure_db_password - DB_PORT=3306 - REDIS_HOST=redis - REDIS_PASSWORD=your_secure_redis_password - REDIS_PORT=6379 - MAIL_MAILER=smtp - MAIL_HOST=smtp.gmail.com - MAIL_PORT=587 - MAIL_USERNAME=your@gmail.com - MAIL_PASSWORD=your_app_password - MAIL_ENCRYPTION=tls - APP_KEY=base64:ZjYwMzQxZTc1ZjIwZjUxZjJhZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZjQwZj...... volumes: - ./storage:/var/www/html/storage - ./bootstrap/cache:/var/www/html/bootstrap/cache - ./nginx/ssl:/etc/nginx/ssl:ro # 只读挂载证书 depends_on: db: condition: service_healthy redis: condition: service_healthy healthcheck: test: ["CMD", "curl", "-f", "http://localhost:80/api/v1/ping"] interval: 30s timeout: 10s retries: 3 # MySQL 数据库 db: image: mysql:8.0 restart: always environment: MYSQL_ROOT_PASSWORD: your_root_password MYSQL_DATABASE: invoice_ninja MYSQL_USER: ninja MYSQL_PASSWORD: your_secure_db_password command: --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci volumes: - ./mysql-data:/var/lib/mysql - ./mysql-conf:/etc/mysql/conf.d healthcheck: test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-u", "root", "-p$$MYSQL_ROOT_PASSWORD"] interval: 30s timeout: 10s retries: 3 # Redis 缓存 redis: image: redis:7-alpine restart: always command: redis-server --requirepass your_secure_redis_password --appendonly yes volumes: - ./redis-data:/data healthcheck: test: ["CMD", "redis-cli", "-h", "localhost", "-a", "your_secure_redis_password", "ping"] interval: 30s timeout: 10s retries: 3

这个配置的关键点：

• healthcheck全覆盖：Nginx 检查/health（需在 Laravel 中添加路由），app 检查/api/v1/ping，db 和 redis 检查服务连通性。depends_on的condition: service_healthy确保容器按依赖顺序启动，避免 app 启动时 db 还没 ready。
• APP_KEY必须生成：运行docker-compose run --rm app php artisan key:generate --show获取，然后粘贴到APP_KEY=后。
• MAIL_*配置使用 Gmail SMTP，MAIL_PASSWORD是 Gmail 的“应用专用密码”，不是登录密码，需在 Google 账户设置中开启两步验证后生成。

4.3 Nginx 配置详解：从 Let’s Encrypt 到 Invoice Ninja 特定优化

./nginx/conf.d/invoice.conf文件内容如下（已去除所有注释，仅保留生产必需）：

upstream invoice_backend { server app:80; } server { listen 80; server_name invoice.yourdomain.com; return 301 https://$server_name$request_uri; } server { listen 443 ssl http2; server_name invoice.yourdomain.com; ssl_certificate /etc/nginx/ssl/fullchain.pem; ssl_certificate_key /etc/nginx/ssl/privkey.pem; ssl_trusted_certificate /etc/nginx/ssl/chain.pem; ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers 'ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384'; ssl_prefer_server_ciphers off; add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always; add_header X-Frame-Options DENY always; add_header X-Content-Type-Options nosniff always; add_header X-XSS-Protection "1; mode=block" always; add_header Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; font-src 'self'; connect-src 'self'; frame-ancestors 'none';" always; client_max_body_size 100M; location / { proxy_pass http://invoice_backend; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header X-Forwarded-Host $server_name; proxy_set_header X-Forwarded-Port 443; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_read_timeout 300; } location ~ /\.env { deny all; } location ~ ^/(vendor|node_modules|storage/app|storage/framework|storage/logs) { deny all; } location ^~ /storage/app/ { alias /var/www/html/storage/app/; internal; } location ^~ /storage/public/ { alias /var/www/html/storage/app/public/; internal; } location = /favicon.ico { log_not_found off; access_log off; } location = /robots.txt { log_not_found off; access_log off; } error_page 404 /index.php; location ~ \.php$ { return 404; } }

重点说明：

• client_max_body_size 100M：允许上传大附件，如扫描的合同 PDF。
• proxy_read_timeout 300：开票生成 PDF 有时耗时较长，避免 Nginx 提前断开连接。
• location ~ \.php$ { return 404; }：强制所有 PHP 请求必须经由 Laravel 路由处理，禁止直接执行任意 PHP 文件，这是防 Webshell 的关键一环。
• internal;指令确保/storage/app/下文件只能通过 Laravel 的Storage::download()方法访问。

4.4 FRP 内网穿透实操：自建服务器 + 客户端一键启动

假设你有一台阿里云轻量应用服务器，公网 IP 为192.0.2.100，已开放端口7000（frps）和80、443（用于反向代理）。在服务器上部署 frps：

# 下载 frp 服务端（Linux amd64） wget https://github.com/fatedier/frp/releases/download/v0.53.3/frp_0.53.3_linux_amd64.tar.gz tar -xzf frp_0.53.3_linux_amd64.tar.gz cd frp_0.53.3_linux_amd64 # 编辑 frps.ini cat > frps.ini << 'EOF' [common] bind_port = 7000 vhost_http_port = 80 vhost_https_port = 443 dashboard_port = 7500 dashboard_user = admin dashboard_pwd = your_dashboard_password EOF # 启动 frps（后台运行） nohup ./frps -c frps.ini > frps.log 2>&1 &

现在，在你的 Invoice Ninja 服务器（本地）上部署 frpc 客户端：

# 下载 frp 客户端（与服务端同版本） wget https://github.com/fatedier/frp/releases/download/v0.53.3/frp_0.53.3_linux_amd64.tar.gz tar -xzf frp_0.53.3_linux_amd64.tar.gz cd frp_0.53.3_linux_amd64 # 编辑 frpc.ini cat > frpc.ini << 'EOF' [common] server_addr = 192.0.2.100 server_port = 7000 [web] type = http local_port = 80 custom_domains = invoice.yourdomain.com [https] type = https local_port = 443 custom_domains = invoice.yourdomain.com EOF # 启动 frpc（后台运行） nohup ./frpc -c frpc.ini > frpc.log 2>&1 &

注意：custom_domains必须与你在 Nginx 配置中写的server_name完全一致，并且该域名的 DNS A 记录必须指向你的 FRP 服务器 IP（192.0.2.100），而不是本地服务器 IP。

验证是否成功：

• 访问http://192.0.2.100:7500，输入admin/your_dashboard_password，看到web和https隧道状态为online。
• 在浏览器访问https://invoice.yourdomain.com，应看到 Invoice Ninja 登录页。
• 查看frpc.log，应有start proxy success日志。

5. 常见问题与排查技巧实录：那些文档里不会写的“血泪经验”

5.1 问题速查表：高频故障与秒级定位法

5.2 实操心得：三个必须写进运维手册的“隐形规则”

第一，永远不要在docker-compose.yml中硬编码敏感信息。我见过太多人把数据库密码、Redis 密码、Gmail 应用密码直接写在environment:下。一旦代码提交到 GitHub，等于把家门钥匙挂在门口。正确做法是使用.env文件（注意：这是 Docker Compose 的.env，不是 Laravel 的.env）：

# 创建 docker-compose.env echo "DB_PASSWORD=your_secure_db_password" > docker-compose.env echo "REDIS_PASSWORD=your_secure_redis_password" >> docker-compose.env echo "MAIL_PASSWORD=your_gmail_app_password" >> docker-compose.env

然后在docker-compose.yml中引用：

environment: - DB_PASSWORD=${DB_PASSWORD} - REDIS_PASSWORD=${REDIS_PASSWORD} - MAIL_PASSWORD=${MAIL_PASSWORD}

最后启动时指定环境文件：docker-compose --env-file docker-compose.env up -d。这样，敏感信息只存在于服务器本地，不随配置文件泄露。

第二，docker-compose down不等于数据清空，但docker volume prune会。很多新手以为down后重跑up就是全新环境，其实./mysql-data、./redis-data、./storage这些挂载卷里的数据都还在。真正想彻底重装，必须：

docker-compose down docker volume prune # 删除所有未使用的卷（谨慎！确认无重要数据） rm -rf ./mysql-data ./redis-data ./storage ./bootstrap/cache

否则，旧数据库的用户表、旧 Redis 的会话，会和新安装的 Invoice Ninja 冲突，导致各种诡异错误。

第三，Let’s Encrypt 证书自动续期必须用certbot的--standalone模式，而非--nginx。因为--nginx模式需要 certbot 直接修改 Nginx 配置，而我们的 Nginx 运行在容器里，宿主机上没有 Nginx。正确流程是：在宿主机上安装 certbot，停掉docker-compose（释放 80/443 端口），运行：

sudo certbot certonly --standalone -d invoice.yourdomain.com --email your@email.com

证书会生成在/etc/letsencrypt/live/invoice.yourdomain.com/。然后在docker-compose.yml中，将./nginx/ssl挂载到这个目录：

volumes: - /etc/letsencrypt/live/invoice.yourdomain.com:/etc/nginx/ssl:ro

最后加个 cron 任务每月自动续期：

# 编辑 crontab sudo crontab -e # 添加一行 0 2 1 * * /usr/bin/certbot renew --quiet --post-hook "docker-compose -f /path/to/docker-compose.yml restart nginx"

5.3 性能调优实战：当客户数突破 500 时的三处关键参数

Invoice Ninja 默认配置适合 50 个客户的小团队。当你的客户列表超过 500 行，搜索变慢、PDF 生成卡顿，这时要调整三处：

1. MySQL 连接池：在./mysql-conf/my.cnf中添加：

   [mysqld] max_connections = 200 wait_timeout = 28800 interactive_timeout = 28800 innodb_buffer_pool_size = 512M # 占用内存的 50%，根据服务器内存调整

2. Redis 内存限制：在docker-compose.yml的redis服务下添加：

   mem_limit: 512m command: redis-server --requirepass your_secure_redis_password --appendonly yes --maxmemory 384mb --maxmemory-policy allkeys-lru

   这样 Redis 不会吃光内存，当内存满时自动淘汰最久未用的 key。

3. Laravel 队列超时：Invoice Ninja 的 PDF 生成、邮件发送走队列。在docker-compose.yml的app环境变量中增加：

   environment: - QUEUE_CONNECTION=redis - QUEUE_TIMEOUT=300 # 队列任务最长运行 5 分钟

   并确保app容器启动时自动运行队列监听：

   # 在 app 服务下添加 command: sh -c "php artisan queue:work --tries=3 --timeout=300 & apache2-foreground"

这些调整不是凭空而来，而是我在一个管理 1200+ 客户的会计事务所项目中，通过htop观察内存、docker stats查看 CPU、redis-cli monitor抓取慢查询，一点一点试出来的。它证明了一件事：开源系统不是“装完就完”，而是需要你像养一棵树一样，根据它的生长状态，不断修剪枝叶、补充养分。

我个人在实际操作中的体会是，Invoice Ninja 的价值，从来不在它有多炫酷的 UI 或多复杂的报表，而在于它把“开票”这件事，从一个黑盒的 SaaS 服务，还原成了一套你可以随时打开、随时修改、随时审计的透明工作流。当你第一次用自己的域名登录，看到那个熟悉的蓝色 Logo，而所有数据都安静地躺在你自己的硬盘上时，那种掌控感，是任何云服务都无法替代的。这个过程或许比点几下鼠标麻烦一点，但麻烦换来的，是真正的数字主权。