这是本节的多页打印视图。点击此处打印.

模块：VIBE

使用 Pigsty 部署 AI 编程沙箱：Code-Server、JupyterLab、Node.js 与 Claude Code。

1: 功能配置
2: 参数列表
3: 预置剧本
4: 管理预案
5: 监控告警
6: 常见问题

VIBE 模块提供一套 浏览器化开发环境，包含 Code-Server、JupyterLab、Node.js 与 Claude Code 的协同配置，并可与 JUICE 共享存储和 PGSQL 数据库能力配合使用。

VIBE 依赖 NODE 与 INFRA：

NODE 负责基础软件与 Python uv 环境
INFRA 提供 Nginx 反向代理、Grafana 等可视化入口

组件一览

组件	说明	本地端口	访问路径
Code-Server	VS Code 浏览器版	8443	`/code/`
JupyterLab	交互式 Notebook	8888	`/jupyter/`
Node.js	运行时与 npm	-	CLI
Claude Code	CLI + 可观测性配置	-	CLI / Grafana

说明：

Code-Server 仅监听 127.0.0.1:8443，通过 Nginx 暴露
JupyterLab 监听 0.0.0.0:8888，默认基路径为 /jupyter/
模块默认 jupyter_enabled: false，而 conf/vibe.yml 模板会显式开启 Jupyter

快速开始

./configure -c vibe
./deploy.yml        # 部署 NODE + INFRA + PGSQL
./juice.yml         # 可选，部署共享存储
./vibe.yml          # 部署 VIBE

默认访问入口（通过 infra_portal.home）：

Code-Server：https://<domain>/code/
JupyterLab：https://<domain>/jupyter/
Claude Dashboard：https://<domain>/ui/d/claude-code

模块特点

统一工作区：vibe_data 作为 Code-Server 与 Jupyter 的根目录
可选共享存储：配合 JUICE 实现多节点共享
可观测性：Claude Code OpenTelemetry 默认对接 VictoriaMetrics/VictoriaLogs
可组件化：Code/Jupyter/Node.js/Claude 可按需启用

文档目录

配置说明：组件配置与工作目录设置
参数详解：VIBE 参数列表与默认值
剧本说明：vibe.yml 使用与标签
管理手册：运维、密码与扩展管理
监控集成：Claude Code 监控与日志
常见问题：FAQ

1 - 功能配置

VIBE 模块配置说明（Code-Server、JupyterLab、Node.js 与 Claude Code）。

VIBE 模块支持按需启用组件，并通过统一的工作目录和 Nginx 入口对外提供服务。

配置概览

组件	启用参数	默认状态	说明
Code-Server	`code_enabled`	启用	浏览器 VS Code
JupyterLab	`jupyter_enabled`	禁用	Notebook/终端/编辑器
Node.js	`nodejs_enabled`	启用	Node.js 运行时与 npm
Claude Code	`claude_enabled`	启用	CLI 配置与可观测性

说明：模块默认 jupyter_enabled: false，但 conf/vibe.yml 预置模板会显式设置为 true。

配置通常位于集群 vars，也可以在实例级别覆盖：

all:
  children:
    infra:
      hosts:
        10.10.10.10:
          vibe_data: /fs
          code_enabled: true
          jupyter_enabled: true
          claude_enabled: true

工作目录

vibe_data 作为 VIBE 的统一工作区：

Code-Server 默认打开目录
JupyterLab root_dir
Claude Code 的工作目录
CLAUDE.md / AGENTS.md 上下文文件

vibe_dir 任务会创建目录并写入上下文文件，文件属主为 node_user。

vibe_data: /fs

Code-Server 配置

code_enabled: true
code_port: 8443
code_data: /data/code
code_password: Vibe.Coding
code_gallery: openvsx

说明：

服务监听 127.0.0.1:<code_port>（默认 8443），通过 Nginx /code/ 访问
配置文件：code_data/code-server/config.yaml（默认 /data/code/code-server/config.yaml）
环境文件：/etc/default/code，用于配置扩展市场

扩展市场：

code_gallery: microsoft 使用微软官方市场
region=china 时默认切换 Open VSX 清华镜像

JupyterLab 配置

jupyter_enabled: true
jupyter_port: 8888
jupyter_data: /data/jupyter
jupyter_password: Vibe.Coding
jupyter_venv: /data/venv

说明：

服务监听 0.0.0.0:<jupyter_port>（默认 8888），基路径为 /jupyter/
配置文件：jupyter_data/jupyter_config.py（默认 /data/jupyter/jupyter_config.py）
登录 Token：c.IdentityProvider.token
不会自动创建 venv，建议通过 NODE 模块的 node_uv_env 预先创建

创建 venv 示例：

uv venv /data/venv

Node.js 配置

nodejs_enabled: true
nodejs_registry: ''
npm_packages:
  - '@anthropic-ai/claude-code'
  - happy-coder

说明：

nodejs_registry 为空时，region=china 会自动使用 https://registry.npmmirror.com
npm_packages 通过 npm install -g 安装，全局可用
默认会安装 @anthropic-ai/claude-code，因此通常无需手工安装 Claude CLI

Claude Code 配置

claude 子任务仅进行配置写入（claude_config）。 Claude CLI 在默认情况下由 nodejs 子任务通过 npm_packages 安装（包含 @anthropic-ai/claude-code）。

claude_enabled: true
claude_env:
  ANTHROPIC_API_KEY: sk-ant-xxx

如果你禁用了 nodejs_enabled 或清空了 npm_packages，则需要手工安装 Claude CLI。

生成的文件：

~/.claude.json
~/.claude/settings.json

claude_env 会与默认 OpenTelemetry 环境变量合并，默认上报到 VictoriaMetrics / VictoriaLogs。

Nginx 入口

VIBE 通过 infra_portal 暴露服务。默认 home 域名自动包含 /code/ 与 /jupyter/ 子路径。

如需独立域名：

infra_portal:
  code: { domain: code.pigsty, endpoint: "127.0.0.1:8443", websocket: true }
  jupyter: { domain: jupyter.pigsty, endpoint: "127.0.0.1:8888", websocket: true }

2 - 参数列表

VIBE 模块参数详解（共 16 项）。

VIBE 模块共有 16 个参数，分为：

通用参数
Code-Server 参数
JupyterLab 参数
Node.js 参数
Claude Code 参数

参数概览

参数	类型	级别	默认值	说明
`vibe_data`	`path`	`C`	`/fs`	工作目录
`code_enabled`	`bool`	`C`	`true`	启用 Code-Server
`code_port`	`port`	`C`	`8443`	Code-Server 端口
`code_data`	`path`	`C`	`/data/code`	Code-Server 数据目录
`code_password`	`string`	`C`	`Vibe.Coding`	Code-Server 密码
`code_gallery`	`enum`	`C`	`openvsx`	扩展市场
`jupyter_enabled`	`bool`	`C`	`false`	启用 JupyterLab
`jupyter_port`	`port`	`C`	`8888`	JupyterLab 端口
`jupyter_data`	`path`	`C`	`/data/jupyter`	JupyterLab 数据目录
`jupyter_password`	`string`	`C`	`Vibe.Coding`	JupyterLab Token
`jupyter_venv`	`path`	`C`	`/data/venv`	Python venv 路径
`nodejs_enabled`	`bool`	`C`	`true`	启用 Node.js
`nodejs_registry`	`url`	`C`	`''`	npm 镜像地址
`npm_packages`	`string[]`	`C`	`['@anthropic-ai/claude-code','happy-coder']`	全局 npm 包
`claude_enabled`	`bool`	`C`	`true`	启用 Claude 配置
`claude_env`	`dict`	`C`	`{}`	Claude 环境变量

默认参数

定义于 roles/vibe/defaults/main.yml：

vibe_data: /fs

code_enabled: true
code_port: 8443
code_data: /data/code
code_password: Vibe.Coding
code_gallery: 'openvsx'

jupyter_enabled: false
jupyter_port: 8888
jupyter_data: /data/jupyter
jupyter_password: Vibe.Coding
jupyter_venv: /data/venv

nodejs_enabled: true
nodejs_registry: ''
npm_packages: [ '@anthropic-ai/claude-code' , 'happy-coder' ]

claude_enabled: true
claude_env: {}

通用参数

`vibe_data`

工作目录，Code-Server 与 JupyterLab 的默认根目录，CLAUDE.md 与 AGENTS.md 也会写入此处。

Code-Server

`code_enabled`

是否启用 Code-Server。

`code_port`

监听端口，绑定 127.0.0.1，由 Nginx /code/ 转发。

`code_data`

用户数据目录，配置文件位于 code_data/code-server/config.yaml（默认 /data/code/code-server/config.yaml）。

`code_password`

登录密码，生产环境必须修改。

`code_gallery`

扩展市场：openvsx / microsoft。当 region=china 且选择 openvsx 时会自动使用清华镜像。

JupyterLab

`jupyter_enabled`

是否启用 JupyterLab。模块默认值为 false，conf/vibe.yml 中会显式改为 true 以启用完整沙箱。

`jupyter_port`

监听端口，默认 0.0.0.0:8888。

`jupyter_data`

数据目录，配置文件位于 jupyter_data/jupyter_config.py（默认 /data/jupyter/jupyter_config.py）。

`jupyter_password`

访问 Token，写入 c.IdentityProvider.token。

`jupyter_venv`

JupyterLab 使用的 Python venv 路径，需要预先创建（通常由 NODE 模块完成）。

Node.js

`nodejs_enabled`

是否启用 Node.js。

`nodejs_registry`

npm 镜像地址，region=china 且为空时自动使用 https://registry.npmmirror.com。

`npm_packages`

全局安装的 npm 包列表，对应标签 nodejs_pkg。默认包含 @anthropic-ai/claude-code 与 happy-coder。

Claude Code

`claude_enabled`

启用 Claude Code 配置任务（claude_config）。 Claude CLI 默认由 nodejs_pkg 根据 npm_packages 安装。

`claude_env`

额外环境变量，合并至默认 OpenTelemetry 配置。

默认环境变量包括：

CLAUDE_CODE_ENABLE_TELEMETRY=1
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
OTEL_METRICS_EXPORTER=otlp
OTEL_LOGS_EXPORTER=otlp
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://127.0.0.1:8428/opentelemetry/v1/metrics
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://127.0.0.1:9428/insert/opentelemetry/v1/logs

3 - 预置剧本

VIBE 模块的 Ansible 剧本使用说明。

VIBE 模块提供 vibe.yml 剧本，用于部署 Code-Server、JupyterLab、Node.js 与 Claude Code 配置。

vibe.yml 只包含 node_id 与 vibe 角色，不包含 node/infra。建议先执行 deploy.yml 或显式运行 node.yml 与 infra.yml。

`vibe.yml`

vibe.yml 内容：

- name: VIBE
  hosts: all
  become: true
  gather_facts: no
  roles:
    - { role: node_id, tags: id }
    - { role: vibe,    tags: vibe }

任务结构

vibe
├── vibe_dir          # 创建工作目录与上下文文件
├── code              # Code-Server
│   ├── code_install
│   ├── code_dir
│   ├── code_config
│   └── code_launch
├── jupyter           # JupyterLab
│   ├── jupyter_install
│   ├── jupyter_dir
│   ├── jupyter_config
│   └── jupyter_launch
├── nodejs            # Node.js Runtime
│   ├── nodejs_install
│   ├── nodejs_config
│   └── nodejs_pkg
└── claude            # Claude Code 配置
    └── claude_config

说明：

jupyter_install 使用 uv pip，不会创建 venv
claude_config 仅写入 ~/.claude 配置
Claude CLI 默认由 nodejs_pkg 按 npm_packages 安装（默认包含 @anthropic-ai/claude-code）

常用命令

完整部署：

./vibe.yml -l <host>

组件级部署：

./vibe.yml -l <host> -t code
./vibe.yml -l <host> -t jupyter
./vibe.yml -l <host> -t nodejs
./vibe.yml -l <host> -t claude

配置更新：

./vibe.yml -l <host> -t code_config,code_launch
./vibe.yml -l <host> -t jupyter_config,jupyter_launch
./vibe.yml -l <host> -t claude_config

禁用组件：

./vibe.yml -l <host> -e code_enabled=false
./vibe.yml -l <host> -e jupyter_enabled=false
./vibe.yml -l <host> -e nodejs_enabled=false
./vibe.yml -l <host> -e claude_enabled=false

部署顺序

./deploy.yml      # NODE + INFRA + PGSQL
./juice.yml       # 可选共享存储
./vibe.yml        # VIBE

幂等性

vibe.yml 支持重复执行，配置变更后可直接重跑。

4 - 管理预案

VIBE 模块运维操作与常见管理任务。

服务管理

systemctl status code-server
systemctl restart code-server
systemctl status jupyter
systemctl restart jupyter

查看日志：

journalctl -u code-server -f
journalctl -u jupyter -f

工作目录与上下文

vibe_dir 会在 vibe_data 下创建：

CLAUDE.md
AGENTS.md（指向 CLAUDE.md 的符号链接）

默认位置（可由 vibe_data 调整）：

/fs/CLAUDE.md
/fs/AGENTS.md

密码与认证

Code-Server

修改配置：

vi /data/code/code-server/config.yaml
systemctl restart code-server

或通过 Ansible：

./vibe.yml -l <host> -e code_password='NewPassword' -t code_config,code_launch

JupyterLab

配置文件位置：/data/jupyter/jupyter_config.py

字段：c.IdentityProvider.token。

vi /data/jupyter/jupyter_config.py
systemctl restart jupyter

Code-Server 扩展

code-server --install-extension ms-python.python
code-server --list-extensions
code-server --uninstall-extension ms-python.python

切换扩展市场：

code_gallery: microsoft

重新部署：

./vibe.yml -l <host> -t code_config,code_launch

JupyterLab 环境管理

VIBE 不会自动创建 venv，请确保 jupyter_venv 存在：

uv venv /data/venv

安装/更新 JupyterLab：

uv pip install --python /data/venv/bin/python jupyterlab ipykernel
systemctl restart jupyter

安装扩展（以 venv 为准）：

source /data/venv/bin/activate
pip install jupyterlab-git
systemctl restart jupyter

Claude Code

claude_config 子任务仅写入配置文件。 Claude CLI 默认由 nodejs_pkg 根据 npm_packages 全局安装（默认包含 @anthropic-ai/claude-code）。

which claude
claude --version

配置文件：

~/.claude.json
~/.claude/settings.json

更新配置：

./vibe.yml -l <host> -t claude_config

重装/补装 Claude CLI：

./vibe.yml -l <host> -t nodejs_pkg
# 或手工安装
npm install -g @anthropic-ai/claude-code

如果需要配置到其他用户，请使用对应的远程登录用户执行或手动拷贝配置文件。

文件位置速查

组件	关键文件
Code-Server	`/data/code/code-server/config.yaml`
Code-Server	`/etc/default/code`
Code-Server	`/etc/systemd/system/code-server.service`
JupyterLab	`/data/jupyter/jupyter_config.py`
JupyterLab	`/etc/default/jupyter`
JupyterLab	`/etc/systemd/system/jupyter.service`
Claude Code	`~/.claude.json` / `~/.claude/settings.json`

故障排查

端口检查：

ss -tlnp | grep 8443
ss -tlnp | grep 8888

Nginx 入口：

nginx -t
systemctl status nginx

5 - 监控告警

VIBE 模块监控说明，重点为 Claude Code 可观测性。

VIBE 的监控主要集中在 Claude Code 的 OpenTelemetry 数据。 Code-Server 与 JupyterLab 本身不暴露 Prometheus 指标，可通过 systemd 与日志进行健康检查。

Claude Code 可观测性

VIBE 在 ~/.claude/settings.json 中写入默认 OpenTelemetry 环境变量：

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": 1,
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": 1,
    "OTEL_LOG_USER_PROMPTS": 1,
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf",
    "OTEL_EXPORTER_OTLP_METRICS_ENDPOINT": "http://127.0.0.1:8428/opentelemetry/v1/metrics",
    "OTEL_EXPORTER_OTLP_LOGS_ENDPOINT": "http://127.0.0.1:9428/insert/opentelemetry/v1/logs",
    "OTEL_RESOURCE_ATTRIBUTES": "ip=<host>,job=claude"
  }
}

claude_env 会与上述默认配置合并，可用于配置 API Key 或替换模型端点。

Grafana Dashboard

Grafana 默认包含 claude-code Dashboard：

Portal 入口：https://<domain>/ui/d/claude-code
直接访问：http://<ip>:3000/d/claude-code

运行状态检查

systemctl status code-server
systemctl status jupyter
journalctl -u code-server -f
journalctl -u jupyter -f

端口检查：

ss -tlnp | grep 8443
ss -tlnp | grep 8888

Claude 日志查询

通过 VictoriaLogs：

curl -G 'http://127.0.0.1:9428/select/logsql/query' \
  --data-urlencode 'query=job:claude'

6 - 常见问题

VIBE 模块常见问题解答。

部署问题

code-server 软件包找不到

确认已部署 NODE 与仓库配置：

yum repolist    # EL
apt update      # Debian/Ubuntu
./infra.yml -t repo

JupyterLab 安装失败

jupyter_venv 必须存在：

uv venv /data/venv
./vibe.yml -l <host> -t jupyter

访问问题

无法访问 `/code/` 或 `/jupyter/`

检查服务状态
检查端口监听
检查 Nginx 配置

systemctl status code-server
systemctl status jupyter
ss -tlnp | grep 8443
ss -tlnp | grep 8888
nginx -t

WebSocket 连接失败

确保 Nginx 配置启用 WebSocket（默认已配置）。若使用自定义 infra_portal，需配置 websocket: true。

密码与 Token

修改 Code-Server 密码

./vibe.yml -l <host> -e code_password='NewPass' -t code_config,code_launch

修改 JupyterLab Token

./vibe.yml -l <host> -e jupyter_password='NewToken' -t jupyter_config,jupyter_launch

Claude Code

CLI 找不到命令

先检查 nodejs_pkg 是否完成（默认会安装 @anthropic-ai/claude-code）：

which claude
npm list -g --depth=0 | grep '@anthropic-ai/claude-code'
./vibe.yml -l <host> -t nodejs_pkg

如果你禁用了 nodejs_enabled 或覆盖了 npm_packages，可手工安装：

npm install -g @anthropic-ai/claude-code

API Key 未配置

export ANTHROPIC_API_KEY=sk-ant-xxx
# 或配置到 claude_env

监控数据不显示

检查本地 VictoriaMetrics/VictoriaLogs：

curl http://127.0.0.1:8428/api/v1/status/buildinfo
curl http://127.0.0.1:9428/select/logsql/stats_query

确保 ~/.claude/settings.json 中 OTEL 端点正确。

扩展与插件

Code-Server 扩展安装失败

检查网络
尝试切换 code_gallery
或手动安装 VSIX

code-server --install-extension /path/to/extension.vsix

JupyterLab 扩展安装失败

source /data/venv/bin/activate
pip install jupyterlab-git
systemctl restart jupyter

模块：VIBE

组件一览

快速开始

模块特点

文档目录

1 - 功能配置

配置概览

工作目录

Code-Server 配置

JupyterLab 配置

Node.js 配置

Claude Code 配置

Nginx 入口

2 - 参数列表

参数概览

默认参数

通用参数

vibe_data

Code-Server

code_enabled

code_port

code_data

code_password

code_gallery

JupyterLab

jupyter_enabled

jupyter_port

jupyter_data

jupyter_password

jupyter_venv

Node.js

nodejs_enabled

nodejs_registry

npm_packages

Claude Code

claude_enabled

claude_env

3 - 预置剧本

vibe.yml

任务结构

常用命令

部署顺序

幂等性

4 - 管理预案

服务管理

工作目录与上下文

密码与认证

Code-Server

JupyterLab

Code-Server 扩展

JupyterLab 环境管理

Claude Code

文件位置速查

故障排查

5 - 监控告警

Claude Code 可观测性

Grafana Dashboard

运行状态检查

Claude 日志查询

6 - 常见问题

部署问题

code-server 软件包找不到

JupyterLab 安装失败

访问问题

无法访问 /code/ 或 /jupyter/

WebSocket 连接失败

密码与 Token

修改 Code-Server 密码

修改 JupyterLab Token

Claude Code

CLI 找不到命令

API Key 未配置

监控数据不显示

扩展与插件

Code-Server 扩展安装失败

JupyterLab 扩展安装失败

`vibe_data`

`code_enabled`

`code_port`

`code_data`

`code_password`

`code_gallery`

`jupyter_enabled`

`jupyter_port`

`jupyter_data`

`jupyter_password`

`jupyter_venv`

`nodejs_enabled`

`nodejs_registry`

`npm_packages`

`claude_enabled`

`claude_env`

`vibe.yml`

无法访问 `/code/` 或 `/jupyter/`