用途:在单台 Vultr 实例上部署并管理自托管 Neon serverless Postgres,包含存储层(storage broker、pageserver、一个 safekeeper)与一个 Postgres 计算节点,pageserver 层和 safekeeper WAL 上传到 Cloudflare R2 的部署专属前缀下,OpenTofu 状态也存于 R2。
安装:npx skills add getcolors/neon;随后 cp .agents/skills/package-neon-green/green ./green 并 chmod +x green。根目录 green 是载荷副本而非符号链接,npx skills update -p 会重写载荷但不改动副本,因此每次更新后需重新复制,否则项目仍运行旧版本。
用法:./green build 渲染 .colors/<profile>/,不调用 provider、不需要凭据;./green create --dry-run 走一遍流程但跳过所有副作用;./green create 真正收敛;./green delete 受保护且具破坏性。build 与 --dry-run 可在全新检出和空环境下安全校验 colors.yml 修改,退出码 2 表示校验或用法失败并一次性列出全部问题。启动器会从工作目录向上查找 colors.yml。
规则:只编辑 colors.yml,键用 kebab-case,仅放非机密值;凭据放在被 gitignore 的 .envrc.private 中的 COLORS_PAR_* 环境变量,绝不写入 colors.yml、生成输出或文档;不要导出 COLORS_PAR_PROFILE,设置后包会拒绝运行;.colors/ 是生成输出,不可编辑、不可当源码读取、不可提交;delete 受 compute-prevent-destroy: true 保护,仅可用 COLORS_PAR_COMPUTE_PREVENT_DESTROY=false 单次解除,不得修改已提交标志,未经明确授权不得对在线部署执行真实 create 或 delete。
连接:除回环外不发布任何内容,无 DNS 记录、无公开 5432,客户端需通过隧道:ssh -L 55433:127.0.0.1:55433 <profile>,再用 psql 'postgresql://<neon-role>@127.0.0.1:55433/<neon-database>'。角色密码在服务器生成,可用 ssh <profile> cat /etc/neon/secrets/neon_role_password 查看;主机上的 neon-status 汇总容器、租户与时间线状态,neon-rotate 原子轮换角色密码并支持回滚。
持久性:pageserver 上传层、safekeeper 卸载已关闭的 WAL 段到 R2 的 <profile>/data/ 下;提交确认仍依赖主机磁盘,上传是异步的,新 safekeeper 无法回放已卸载的 WAL,因此整机丢失只能恢复 pageserver 已上传内容,单节点 RPO 为上次检查点上传之后的活动。主机存活但存储层被清空不会丢数据(已演练)。这是演示级部署,切勿在桶上配置 R2 生命周期规则,否则会删除活跃的层与 WAL。
参考:references/configuration.md 记录每个 colors.yml 键、每个凭据及恢复流程。计算委托给固定版本的 colors-compute 库,其单例拓扑保持仅 SSH 公网入口与回环应用服务;R2 或 S3 状态位于 <profile>/compute/shared.tfstate 与 <profile>/compute/nodes/0.tfstate,并带部署日志,不支持本地计算状态;已存在的 <profile>/neon-infrastructure.tfstate 会被拒绝,需操作者显式迁移,绝不静默采用。该迁移未执行真实部署。