Pigsty Vibe 环境 AGENTS.md 完全指南：为 AI 编程助手打造的 PostgreSQL 沙箱使用手册

• 数据库
• 运维
• 云原生
• 高可用
• 监控

Pigsty 的 Vibe（Vibe Coding）模块在部署时会在工作区根目录渲染一份名为AGENTS.md的环境上下文文档，它既是进入该 AI 编程沙箱的"使用说明书"，也是 Claude Code 等编码智能体的自动上下文来源。本文以该文档为核心，结合 vibe 角色 的源码与 conf/vibe.yml 配置样例，系统讲解沙箱内的服务接入点、PostgreSQL 使用规范、数据目录布局、可观测性与 Web 发布能力。读完本文，你将能在该环境内正确连接数据库、查询指标与日志、发布静态站点，并理解 AGENTS.md 是如何被渲染、如何被 AI 智能体引用的。

一、AGENTS.md 从何而来：vibe 角色的上下文渲染机制

AGENTS.md并不是一份手写静态文档，而是由 Pigsty 的 vibe 角色 在部署阶段通过 Jinja2 模板渲染生成的运行时文件。在 roles/vibe/tasks/main.yml 的vibe_dir任务块中可以看到完整链路：

1. 创建{{ vibe_data }}工作区目录（默认/fs），属主与属组取node_user（默认 root），权限0755；
2. 检查{{ vibe_data }}/AGENTS.md是否已存在且为旧版符号链接，若是则先移除（避免遗留的CLAUDE.md软链失效）；
3. 用template模块将AGENTS.md渲染到{{ vibe_data }}/AGENTS.md，权限0644；
4. 最后创建CLAUDE.md -> AGENTS.md的符号链接，使 Claude Code 能自动读取到这份上下文。

这意味着文档中的{{ inventory_hostname }}、{{ pg_admin_username | default('dbuser_dba') }}、{{ pg_admin_password | default('DBUser.DBA') }}、{{ pg_version | default(18) }}、{{ pg_cluster | default('pg-meta') }}、{{ vibe_data | default('/fs') }}等占位符，在部署时都会被替换为实际值——读者看到的就是针对当前节点定制后的"事实说明书"。文档开头的Pigsty Vibe Coding Environment与主机名横幅，正是用来向智能体声明当前环境的身份与定位。

二、环境总览：一次对话能调用哪些能力

AGENTS.md 开门见山地定义了该环境的定位：通过自然语言对话创建应用、站点与可视化（vibe coding）。它列出的"你有什么"（What you have）构成了一份能力清单：

• PostgreSQL：存储数据、建表、执行查询，是沙箱的数据底座；
• Nginx：在http://{{ inventory_hostname }}/提供静态/动态内容发布；
• 可观测性：VictoriaMetrics（指标）、VictoriaLogs（日志）、Grafana（仪表盘）三件套；
• AI CLI：启用 VIBE 角色时 Claude Code 为默认编码智能体，codex可选安装；
• Python：位于/data/venv/bin/python，必须用uv pip install安装包，严禁动系统 Python；
• Hugo：用于构建静态站点（仓库内可用，yum/apt install hugo安装）；
• Golang：可通过yum/apt install golang按需安装。

如果能力不够，Pigsty 还提供 Redis、MinIO、etcd、Docker 等组件按需安装。同时文档给出两条硬性规则：主数据目录是/data，不要改动其中已有的子目录。

从 roles/vibe/defaults/main.yml 可以看到，这套能力的开关全部由变量控制：code_enabled、jupyter_enabled、claude_enabled、codex_enabled、nodejs_enabled默认均为true（Jupyter 默认false，在conf/vibe.yml中显式开启），并可通过./vibe.yml -e xxx_enabled=false按需裁剪（详见 roles/vibe/README.md 的 Usage 一节）。

三、服务接入点速查表

AGENTS.md 的 Services 一节给出了沙箱内全部服务的端口与连接方式，整理如下：

注意连接串中数据库用户默认是dbuser_dba、密码DBUser.DBA，这些默认值来自 conf/vibe.yml 中的pg_users定义（dbuser_meta/dbuser_view）与全局密码变量（pg_admin_password: DBUser.DBA、grafana_admin_password: pigsty）。如果读者实际部署时修改过密码，应以pigsty.yml中为准。

四、配置即真相：pigsty.yml 是唯一事实来源

AGENTS.md 反复强调：配置文件~/pigsty/pigsty.yml是唯一事实来源（single source of truth），智能体或人工排查环境时首先应读它。文档给出了三条高频探测命令：

cat ~/pigsty/pigsty.yml # view full config grep -A5 'pg_users:' ~/pigsty/pigsty.yml # find database users grep -A5 'pg_databases:' ~/pigsty/pigsty.yml # find databases

同时列出了pigsty.yml的关键结构：

• all.children.<cluster>.hosts— 节点清单（inventory）；
• all.children.<cluster>.vars.pg_users— 数据库用户（name、password、roles）；
• all.children.<cluster>.vars.pg_databases— 数据库（name、owner、extensions）；
• all.vars— 全局默认值。

以 conf/vibe.yml 为实例可以直观印证这套结构：pgsql集群定义在10.10.10.10上（pg_role: primary单节点），pg_users中dbuser_meta拥有dbrole_admin角色、dbuser_view拥有dbrole_readonly；pg_databases中定义了meta库，带postgis, timescaledb, vector, age扩展与pigstyschema。这份配置正是 AGENTS.md 中被智能体反复查阅的"环境地图"。

五、PostgreSQL 使用规范与维护命令

5.1 连接与建库原则

沙箱内的 PostgreSQL 为PG {{ pg_version | default(18) }}（conf/vibe.yml中pg_version: 18），集群名默认pg-meta，预置 555 个扩展。两种连接方式：

psql 'postgres://dbuser_dba:DBUser.DBA@127.0.0.1/postgres' # admin sudo -iu postgres psql # superuser via socket

文档给出了明确的建库纪律，对智能体尤其重要：

• 优先使用当前集群中已有的meta数据库，仅在必要时才新建专用库；
• 避免使用postgres与template1数据库（它们是系统库，应保持纯净）；
• 简单应用可直接使用publicschema，复杂应用则创建专属 schema。

5.2 管理命令与备份

该环境是裁剪后的单节点 Pigsty，不含 pgbouncer 与 patroni（conf/vibe.yml中pgbouncer_enabled: false、patroni_mode: remove），因此管理命令更直接：

pg-backup full # 立即全量备份（也支持 incr / diff） bin/pgsql-user pg-meta <user> # 创建用户（先在 pigsty.yml 中定义） bin/pgsql-db pg-meta <db> # 创建数据库（先在 pigsty.yml 中定义）

目录约定：数据/pg/data、日志/pg/log、备份/pg/backup。备份由 pgBackRest 驱动，配置在/etc/pgbackrest/，恢复/备份分别使用pg-backup与pg-pitr两个 CLI 工具（对应仓库中的 files/postgres/pg-backup 与 files/postgres/pg-pitr）。conf/vibe.yml中通过pg_crontab: [ '00 01 * * * /pg/bin/pg-backup full' ]默认在每天凌晨 1 点做一次全量备份。

六、数据目录布局与磁盘规则

AGENTS.md 用一张目录树明确了沙箱的磁盘约定：

/data/ # 主数据目录（DO NOT TOUCH existing subdirs） ├── postgres/ # pg tablespace ├── backups/ # pg backup repo ├── venv/ # python venv └── ... /www/ # nginx static root /fs/ # vibe workspace（code-server 与 jupyter 根目录，由 {{ vibe_data }} 控制） ~/pigsty/ # pigsty 源码与配置

铁律：应用产生的数据应放在{{ vibe_data | default('/fs') }}/或/data/<yourapp>/，绝不修改既有目录。这条规则既保护了 PostgreSQL、备份库与 venv 等基础设施，也让智能体的文件操作有明确边界。vibe_data默认/fs（roles/vibe/defaults/main.yml），在conf/vibe.yml中通常由 JuiceFS 挂载（juice_instances.jfs.path: /fs），即一个以 PostgreSQL 为元数据存储的分布式文件系统。

七、可观测性：VictoriaMetrics / VictoriaLogs / Grafana

7.1 查询与写入命令

AGENTS.md 给出了指标与日志的即用命令：

curl 'http://127.0.0.1:8428/api/v1/query?query=pg_up' # 查询指标（PromQL） curl 'http://127.0.0.1:9428/select/logsql/query?query=*' # 查询日志（LogsQL） curl -X POST 'http://127.0.0.1:8428/opentelemetry/v1/metrics' -d # 推送指标（OTLP） curl -X POST 'http://127.0.0.1:9428/insert/opentelemetry/v1/logs' -d # 推送日志（OTLP）

Grafana 预置 PGSQL、NODE、INFRA 三类仪表盘，访问http://{{ inventory_hostname }}:3000。conf/vibe.yml还在infra_extra_services中为首页门户注册了 Code Server（/code）、Jupyter（/jupyter）、Claude Code 可观测性（/ui/d/claude-code）三个入口。

7.2 Claude Code 的 OTEL 集成（源码级）

AGENTS.md 提到 "Claude Code emits OTEL logs and metrics to the local Victoria stack asjob=claude"。这一行为由 roles/vibe/tasks/claude.yml 中的claude_config任务落地：角色会向~/.claude/settings.json写入一组默认环境变量：

同时角色会渲染~/.claude.json（跳过 onboarding 向导与信任弹窗，置为hasCompletedOnboarding: true等），让 Claude Code 开箱即用。需要强调：提示词内容默认不采集，若需接入，只能通过claude_env变量显式配置（见 roles/vibe/README.md）。若使用第三方 Anthropic 兼容 API，可在claude_env中设置ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN、API_TIMEOUT_MS等（conf/vibe.yml 中也有示例注释）。

八、Web 发布：Nginx /www/ 的三种姿势

Nginx 将/www/作为文档根映射到http://{{ inventory_hostname }}/，AGENTS.md 给出了三种发布形态：

• 静态 HTML：把文件写到/www/mypage.html，即可通过/mypage.html访问；
• 静态站点：用仓库内置的 Hugo 构建，输出到/www/mysite/；
• 动态应用：应用跑在某个端口上，直接访问该端口，或通过 Nginx 反代暴露。

Nginx 还具备域名、HTTPS 证书处理能力，沙箱默认通过 Nginx 将 Code Server 暴露为https://<host>/code/、JupyterLab 为https://<host>/jupyter/（访问方式见 roles/vibe/README.md 的 Access 表）。从 roles/vibe/templates/code.svc 可以看到 code-server 以 systemd 服务形式运行，WorkingDirectory={{ vibe_data }}、绑定127.0.0.1:{{ code_port }}、Restart=always，默认端口 8443、密码由code_password控制；扩展市场默认走 openvsx，region=china时自动切换到清华 open-vsx 镜像（roles/vibe/templates/code.env）。

九、参考资源与延伸阅读

AGENTS.md 文末给出的参考入口，均可在仓库内找到对应实体进行深入阅读：

• PGSQL 管理：用户/数据库创建见 bin/pgsql-user 与 bin/pgsql-db 两条 playbook，备份恢复见 pg-backup 与 pg-pitr；
• 配置体系：pigsty.yml的全局结构见 pigsty.yml，Vibe 沙箱完整模板见 conf/vibe.yml；
• 扩展清单：conf/vibe.yml的pg_extensions展示了pg18-main/time/gis/rag/fts/olap/feat/lang/type/util/func/admin/stat/sec/fdw/sim/etl共 17 组扩展包；
• CLI 工具集：bin/pgsql-*、bin/node-*、bin/redis-*对应 PGSQL、节点与 Redis 三大运维命令族；
• VIBE 角色本体：roles/vibe/README.md 完整记录了变量表、Tags 层级（vibe_dir/code/jupyter/nodejs/claude/codex）与按需部署命令，例如只装 Code Server 用./vibe.yml -l <host> -t code。

结语

AGENTS.md本质上是 Pigsty 为 AI 智能体量身定制的"环境宪法"：它把数据库、可观测性、Web 发布、磁盘纪律与配置真相源浓缩成一份可被 Claude Code 自动读取的上下文文件，同时保留了足够的人工可读性。理解这份文档及其背后的 vibe 角色 渲染机制，就等于掌握了在 Pigsty 单节点沙箱中安全、高效地进行 AI 辅助开发的全部规矩与能力边界——无论是用meta库构建应用、用 Victoria 栈观测智能体行为，还是用/www/发布成果，都能做到心中有数、有据可查。

• 数据库
• 运维
• 云原生
• 高可用
• 监控