部署

互客鱼以 Laravel Cloud 作为主要目标构建 — 技术栈是 FrankenPHP + Postgres + Redis，Laravel Cloud 原生提供所有这些。 支持自托管，但操作员拥有更多部分。

Laravel Cloud

仓库中的 infra/cloud.yaml 描述了环境和进程。高层形状：

• 区域：默认 us-east。根据客户接近度选择。
• 应用进程：FrankePHP，Octane 模式。自动扩展。
• Worker 进程：Horizon，专用于 crawl、index 和 default 队列。
• Reverb 进程：持久 WebSocket 服务器。
• Postgres：16，每日备份。
• Redis：7，持久化。

环境

环境	用途
preview	每个 PR 的临时环境。PR 打开时自动启动，合并/关闭时拆除。
staging	长期存在。镜像生产配置。用于 QA 和预发布验证。
production	面向客户的环境。发布需要绿色 CI + 手动部署。

v1 发布的计算大小

起点。根据流量调整。

组件	大小	原因
应用 (Octane)	2 实例 × 2 vCPU / 2 GB	热路径主要在 LLM 流式传输上是 I/O 绑定的。两个实例用于 HA。
Worker (Horizon)	2 实例 × 2 vCPU / 2 GB	索引吞吐量。按队列深度扩展。
Reverb	1 实例 × 1 vCPU / 1 GB	WebSocket，粘性。
Postgres	2 vCPU / 4 GB / 50 GB SSD	直到约 10M 消息都很舒适。
Redis	1 GB	会话、队列、热缓存。

域

您通常需要：

• 主域 — amc.hukeyu.com 用于客户/管理应用。
• 小部件域 — 相同或单独的 cdn.hukeyu.com 提供 /widget/widget.js。包有内容哈希查询参数，因此激进的缓存是安全的。
• Reverb 域 — realtime.hukeyu.com 如果您将 WebSocket 进程拆分到自己的主机上。

CI/CD

GitHub Actions 工作流在 .github/workflows/ 下：

• tests.yml — PHP 设置 + Composer + Pest 套件（使用 fakes，无网络）。
• lint.yml — Pint、ESLint、TypeScript tsc --noEmit。
• widget.yml — 小部件包构建 + 大小预算检查。

部署需要绿色 CI；实际的部署步骤配置在 Laravel Cloud （或您的托管等效项）上，而不是在工作流文件中。

迁移

Laravel Cloud 在每次部署时运行 php artisan migrate --force。 迁移应该是向后兼容的 — 向填充的表添加 NOT NULL 列的部署需要两步：

1. 部署 1：添加可空列，回填，应用代码开始写入它。
2. 部署 2：将列更改为 NOT NULL。

重命名和删除也是如此 — 永远不要在单次部署中进行破坏性操作。

备份

• Postgres — 每日快照，保留 30 天。启用时间点恢复。
• 向量存储 — Cloudflare Vectorize / Qdrant 没有内置备份；通过为每个文档重新分发 IndexDocumentJob 从 chunks 表重建。php artisan hukeyu:audit-vectors 报告 chunks 表和实时向量存储之间的漂移；如果需要修复，按行分派作业。
• R2 / 对象存储 — 启用版本控制。
• 应用秘密 — Laravel Cloud 的秘密存储已加密；单独备份 APP_KEY（它是 app_settings 加密的主密钥）。

回滚

Laravel Cloud 保留上一个版本以进行即时回滚。对于架构不兼容的回滚 （罕见），从最新快照恢复。

自托管

支持生产的 Docker 设置与 docker-compose.yml 相同， 但有一些补充：

• 反向代理（Caddy 或 Nginx）在 FrankenPHP 前终止 TLS。
• 托管 Postgres + Redis（或自管理带 HA 副本）。
• Horizon 作为长期运行的服务，由 systemd / 进程管理器监控。
• Reverb 作为自己的进程。
• Sentry / OTEL 收集器本地运行或指向 SaaS。

composer run dev 快捷方式在本地启动所有内容 （Octane、队列 worker、Reverb、vite）用于开发。