这是本节的多页打印视图。 .

返回本页常规视图.

模块：VIBE

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

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

VIBE 依赖 NODE 与 INFRA：

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

组件一览

组件说明本地端口访问路径
Code-ServerVS Code 浏览器版8443/code/
JupyterLab交互式 Notebook8888/jupyter/
Node.js运行时与 npm-CLI
Claude CodeCLI + 可观测性配置-CLI / Grafana
Codex CLICLI 安装，不托管配置-CLI

说明：

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

快速开始

BASH
./configure -c vibe
./deploy.yml        # 部署清单中已定义的 NODE、INFRA、ETCD、MINIO 与 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/Codex 可按需启用

文档目录

1 - 功能配置

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

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

配置概览

组件启用参数默认状态说明
Code-Servercode_enabled启用浏览器 VS Code
JupyterLabjupyter_enabled禁用Notebook/终端/编辑器
Node.jsnodejs_enabled启用Node.js 运行时与 npm
Claude Codeclaude_enabled启用CLI 安装、配置与可观测性
Codex CLIcodex_enabled启用仅安装 CLI，不托管配置

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

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

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

工作目录

vibe_data 作为 VIBE 的统一工作区：

  • Code-Server 默认打开目录
  • JupyterLab root_dir
  • Claude Code 的工作目录
  • 渲染 AGENTS.md 上下文文件，并创建指向它的 CLAUDE.md 符号链接

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

YAML
vibe_data: /fs

Code-Server 配置

YAML
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 配置

YAML
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 示例：

BASH
uv venv /data/venv

Node.js 配置

YAML
nodejs_enabled: true
nodejs_registry: ''
npm_packages: []

说明：

  • nodejs_registry 为空时，region=china 会自动使用 https://registry.npmmirror.com
  • npm_packages 用于安装额外的全局 npm 包，默认为空
  • Claude Code 与 Codex CLI 由各自的独立任务安装

Claude Code 配置

claude 子任务同时执行 CLI 安装（claude_install）与配置写入（claude_config）。

YAML
claude_enabled: true
claude_package: '@anthropic-ai/claude-code'
claude_env:
  ANTHROPIC_API_KEY: sk-ant-xxx

启用 Claude 或 Codex 时，VIBE 会确保 Node.js 运行时已经安装。需要替换 Claude npm 包时，可覆盖 claude_package。

生成的文件：

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

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

Codex CLI 配置

YAML
codex_enabled: true

codex 子任务执行 npm install -g @openai/codex。VIBE 仅安装 Codex CLI，不写入 Codex 配置，也不接入 VIBE 的 Claude Code 可观测性。

Nginx 入口

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

如需独立域名：

YAML
infra_portal:
  code: { domain: code.pigsty, endpoint: "127.0.0.1:8443", websocket: true, auth: true }
  jupyter: { domain: jupyter.pigsty, endpoint: "127.0.0.1:8888", websocket: true, auth: true }
nginx_users:
  devadmin: '<strong-password>'

2 - 参数列表

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

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

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

参数概览

参数类型级别默认值说明
vibe_datapathC/fs工作目录
code_enabledboolCtrue启用 Code-Server
code_portportC8443Code-Server 端口
code_datapathC/data/codeCode-Server 数据目录
code_passwordstringCVibe.CodingCode-Server 密码
code_galleryenumCopenvsx扩展市场
jupyter_enabledboolCfalse启用 JupyterLab
jupyter_portportC8888JupyterLab 端口
jupyter_datapathC/data/jupyterJupyterLab 数据目录
jupyter_passwordstringCVibe.CodingJupyterLab Token
jupyter_venvpathC/data/venvPython venv 路径
nodejs_enabledboolCtrue启用 Node.js
nodejs_registryurlC''npm 镜像地址
npm_packagesstring[]C[]额外全局 npm 包
claude_enabledboolCtrue安装并配置 Claude Code
claude_packagestringC@anthropic-ai/claude-codeClaude Code npm 包
claude_envdictC{}Claude 环境变量
codex_enabledboolCtrue安装 Codex CLI

默认参数

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

YAML
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: []

claude_enabled: true
claude_package: '@anthropic-ai/claude-code'
claude_env: {}

codex_enabled: true

通用参数

vibe_data

工作目录，默认值为 /fs。Code-Server 与 JupyterLab 默认以此作为工作区根目录；vibe_dir 会在这里渲染 AGENTS.md，并创建指向它的 CLAUDE.md 符号链接。

Code-Server

code_enabled

是否启用 Code-Server，默认值为 true。

code_port

监听端口，默认值为 8443；绑定 127.0.0.1，由 Nginx /code/ 转发。

code_data

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

code_password

登录密码，默认值为 Vibe.Coding，生产环境必须修改。

扩展市场：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，默认值为 Vibe.Coding，写入 c.IdentityProvider.token。

jupyter_venv

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

Node.js

nodejs_enabled

是否启用独立的 Node.js 安装任务，默认值为 true。

nodejs_registry

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

npm_packages

额外全局安装的 npm 包列表，对应标签 nodejs_pkg，默认为空。 Claude Code 与 Codex CLI 由各自的独立任务安装，不需要加入此列表。

Claude Code

claude_enabled

启用 Claude Code 安装与配置任务，默认值为 true。claude_install 安装 CLI，claude_config 写入配置。

claude_package

Claude Code 使用的 npm 包，默认为 @anthropic-ai/claude-code。

claude_env

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

默认环境变量包括：

  • CLAUDE_CODE_ENABLE_TELEMETRY=1
  • OTEL_METRICS_EXPORTER=otlp
  • OTEL_LOGS_EXPORTER=otlp
  • OTEL_EXPORTER_OTLP_METRICS_PROTOCOL=http/protobuf
  • OTEL_EXPORTER_OTLP_LOGS_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=<inventory_hostname>,job=claude

Codex CLI

codex_enabled

是否安装 Codex CLI，默认为 true。启用后，codex_install 任务执行 npm install -g @openai/codex。 VIBE 只负责安装 Codex CLI，不托管 Codex 配置，也不为其配置 OpenTelemetry。

3 - 预置剧本

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

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

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

vibe.yml

vibe.yml 内容：

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

任务结构

BASH
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 与额外 npm 包
│   ├── nodejs_install
│   ├── nodejs_config
│   └── nodejs_pkg
├── codex             # Codex CLI
│   └── codex_install
└── claude            # Claude Code
    ├── claude_install
    └── claude_config

说明：

  • jupyter_install 使用 uv pip，不会创建 venv
  • nodejs_pkg 只安装 npm_packages 中声明的额外包，默认列表为空
  • claude_install 使用 claude_package 安装 Claude CLI，claude_config 写入 ~/.claude 配置
  • codex_install 安装 @openai/codex，不托管 Codex 配置

常用命令

完整部署：

BASH
./vibe.yml -l <host>

组件级部署：

BASH
./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 codex

配置更新：

BASH
./vibe.yml -l <host> -t code_config,code_launch
./vibe.yml -l <host> -t jupyter_config
ssh <host> sudo systemctl restart jupyter
./vibe.yml -l <host> -t claude_config

在本次执行中跳过组件：

BASH
./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
./vibe.yml -l <host> -e codex_enabled=false

这些开关是任务执行条件：设为 false 只会跳过对应安装与配置任务，不会停止、禁用或卸载此前已经部署的服务/软件。若要退役 Code-Server 或 JupyterLab，需要另行执行 systemctl disable --now code-server 或 systemctl disable --now jupyter；VIBE 当前没有独立的移除剧本。

Node.js 是 Claude Code 与 Codex CLI 的运行时依赖：只设置 nodejs_enabled=false，但 claude_enabled 或 codex_enabled 仍为 true 时，nodejs 阶段依然会执行。只有三个开关都为 false 时才会跳过 Node.js 阶段。

部署顺序

BASH
./deploy.yml      # 清单中已定义的 NODE、INFRA、ETCD、MINIO 与 PGSQL
./juice.yml       # 可选共享存储
./vibe.yml        # VIBE

幂等性

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

4 - 管理预案

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

服务管理

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

查看日志：

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

工作目录与上下文

vibe_dir 会在 vibe_data 下创建：

  • AGENTS.md：由角色模板渲染的上下文文件
  • CLAUDE.md：指向 AGENTS.md 的符号链接

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

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

密码与认证

Code-Server

修改配置：

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

或通过 Ansible：

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

JupyterLab

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

字段：c.IdentityProvider.token。

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

Code-Server 扩展

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

切换扩展市场：

YAML
code_gallery: microsoft

重新部署：

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

JupyterLab 环境管理

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

BASH
uv venv /data/venv

安装/更新 JupyterLab：

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

安装扩展（以 venv 为准）：

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

Claude Code

claude_install 子任务安装 Claude CLI，claude_config 子任务写入配置文件。

BASH
which claude
claude --version

配置文件：

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

更新配置：

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

重装/补装 Claude CLI：

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

需要使用其他 npm 包时，可覆盖 claude_package。

Codex CLI

VIBE 通过 codex_install 安装 @openai/codex，但不托管 Codex 配置：

BASH
which codex
codex --version
./vibe.yml -l <host> -t codex_install

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

文件位置速查

组件关键文件
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

故障排查

端口检查：

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

Nginx 入口：

BASH
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 环境变量：

JSON
{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_METRICS_PROTOCOL": "http/protobuf",
    "OTEL_EXPORTER_OTLP_LOGS_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

运行状态检查

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

端口检查：

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

Claude 日志查询

通过 VictoriaLogs：

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

6 - 常见问题

VIBE 模块常见问题解答。

部署问题

code-server 软件包找不到

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

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

JupyterLab 安装失败

jupyter_venv 必须存在：

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

访问问题

无法访问 /code/ 或 /jupyter/

  1. 检查服务状态
  2. 检查端口监听
  3. 检查 Nginx 配置
BASH
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 密码

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

修改 JupyterLab Token

BASH
./vibe.yml -l <host> -e jupyter_password='NewToken' -t jupyter_config
ssh <host> sudo systemctl restart jupyter

Claude Code

CLI 找不到命令

先检查 claude_install 是否完成：

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

如果你禁用了 claude_enabled，可手工安装：

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

需要替换 npm 包时，可通过 claude_package 指定。

Codex CLI 找不到命令

BASH
which codex
npm list -g --depth=0 | grep '@openai/codex'
./vibe.yml -l <host> -t codex_install

确认 codex_enabled: true。VIBE 仅安装 Codex CLI，不负责生成 Codex 配置。

API Key 未配置

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

监控数据不显示

检查本地 VictoriaMetrics/VictoriaLogs：

BASH
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
BASH
code-server --install-extension /path/to/extension.vsix

JupyterLab 扩展安装失败

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