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

返回本页常规视图.

模块:VIBE

使用 Pigsty 部署 AI 编程沙箱,包含 Code-Server、JupyterLab 和 Claude Code 三大组件。

VIBE 模块提供了一套完整的 云端开发环境,将浏览器中的 VS Code、交互式计算平台 JupyterLab 以及 AI 辅助编程工具 Claude Code 整合在一起, 配合 JuiceFS 分布式文件系统和功能丰富的 PostgreSQL 数据库,打造开箱即用的 AI 编程沙箱


模块组件

VIBE 模块包含三个核心组件:

组件说明默认端口访问路径
Code-Server浏览器中的 VS Code,完整的云端 IDE 体验8443/code/
JupyterLab交互式计算环境,支持 Notebook、终端、编辑器8888/jupyter/
Claude CodeAnthropic 的 AI 编程助手 CLI 工具,集成可观测性-CLI / Dashboard

架构概览

VIBE 组件部署为 systemd 服务,通过 Nginx 反向代理提供 HTTPS 访问:

用户浏览器
    │
    ├── https://h.pigsty/code/     ─────► Code-Server  (127.0.0.1:8443)
    ├── https://h.pigsty/jupyter/  ─────► JupyterLab   (127.0.0.1:8888)
    └── https://h.pigsty:3000/d/claude-code ──► Grafana Dashboard

命令行
    └── ssh user@h.pigsty ──► Claude Code CLI

共享存储
    └── JuiceFS (/fs) ─────► PostgreSQL (元数据 + 数据)

模块特点

  • 云端 IDE:通过浏览器访问完整的 VS Code 开发环境,随时随地编程
  • 交互式计算:JupyterLab 提供 Notebook、终端、编辑器等多功能界面
  • AI 编程助手:Claude Code CLI 集成 OpenTelemetry 可观测性,支持监控分析
  • 共享存储:配合 JuiceFS 实现文件系统共享,支持时间点恢复(PITR)
  • 丰富的 PostgreSQL:预装 400+ 扩展,覆盖向量、时序、地理、分析等场景
  • 一键部署:通过 Ansible 剧本自动化安装配置,开箱即用

快速开始

1. 准备配置

使用 vibe 配置模板:

./configure -c vibe

2. 部署基础设施

./deploy.yml    # 部署 INFRA + PGSQL
./juice.yml     # 部署 JuiceFS 共享存储(可选)

3. 部署 VIBE 模块

./vibe.yml      # 部署 Code-Server + JupyterLab + Claude Code

4. 访问服务

服务地址默认凭证
Code-Serverhttps://<ip>/code/Code.Server
JupyterLabhttps://<ip>/jupyter/Jupyter.Lab
Claude 监控https://<ip>:3000/d/claude-codeGrafana 凭证

配置示例

典型的 VIBE 配置示例(参见 conf/vibe.yml):

all:
  children:
    infra:
      hosts:
        10.10.10.10:
          # VIBE 组件配置
          vibe_data: /fs                    # 工作目录(JuiceFS 挂载点)
          code_enabled: true                # 启用 Code-Server
          code_password: 'Code.Server'      # Code-Server 密码
          jupyter_enabled: true             # 启用 JupyterLab
          jupyter_password: 'Jupyter.Lab'   # JupyterLab Token
          claude_enabled: true              # 启用 Claude Code

          # JuiceFS 共享存储
          juice_instances:
            jfs:
              path: /fs
              meta: postgres://dbuser_meta:DBUser.Meta@10.10.10.10:5432/meta
              data: --storage postgres --bucket postgres://dbuser_meta:DBUser.Meta@10.10.10.10:5432/meta?prefix=juice

预装工具

VIBE 配置模板预装了以下开发工具:

工具说明
claudeAnthropic Claude Code CLI
opencode开源 AI 编程助手
code-server浏览器中的 VS Code
golangGo 语言工具链
nodejsNode.js 运行时
uv高性能 Python 包管理器
postgrestPostgreSQL RESTful API 服务
genai-toolboxGoogle GenAI Toolbox MCP 服务
restic增量备份工具
rclone云存储同步工具
asciinema终端录屏工具

PostgreSQL 扩展

VIBE 配置模板的 PostgreSQL 预装了丰富的扩展:

  • 向量搜索pgvectorpgvectorscale
  • 时序分析timescaledbpg_timeseries
  • 地理空间postgish3pgrouting
  • 数据分析pg_duckdbpg_analyticshydra
  • 全文搜索pg_searchzhparser
  • 安全增强pg_tdesupabase_vaultpgsodium
  • 更多扩展:详见 扩展目录

使用场景

  • AI 辅助开发:利用 Claude Code 进行智能编程,提升开发效率
  • 数据科学:JupyterLab + PostgreSQL + 向量/时序扩展,构建分析平台
  • 远程开发:在任何设备上通过浏览器访问完整开发环境
  • 教学培训:快速搭建标准化的教学环境,降低环境配置门槛
  • 原型验证:快速搭建 PoC 环境,验证技术方案

注意事项


文档目录

1 - 配置 VIBE

VIBE 模块的配置说明,包括 Code-Server、JupyterLab 和 Claude Code 的详细配置方法。

VIBE 模块提供了灵活的配置选项,可以根据需求启用或禁用各个组件,并自定义其行为。


配置概览

VIBE 模块包含三个可独立配置的组件:

组件启用参数默认状态说明
Code-Servercode_enabled启用浏览器中的 VS Code
JupyterLabjupyter_enabled启用交互式计算环境
Claude Codeclaude_enabled启用AI 编程助手 CLI

配置位于 Pigsty 配置文件的主机变量或组变量中:

all:
  children:
    infra:
      hosts:
        10.10.10.10:
          # VIBE 配置
          vibe_data: /fs
          code_enabled: true
          jupyter_enabled: true
          claude_enabled: true

Code-Server 配置

基本配置

code_enabled: true           # 启用 Code-Server
code_port: 8443              # 监听端口(仅 localhost)
code_data: /data/code        # 用户数据目录
code_password: 'Code.Server' # 登录密码
code_gallery: openvsx        # 扩展市场

扩展市场选项

Code-Server 支持多种扩展市场:

选项说明
openvsxOpen VSX 开源市场(默认)
microsoft微软官方市场

中国大陆用户会自动使用清华镜像加速。

配置示例

# 使用微软扩展市场
code_enabled: true
code_password: 'MySecretPassword'
code_gallery: microsoft
code_data: /data/code

JupyterLab 配置

基本配置

jupyter_enabled: true           # 启用 JupyterLab
jupyter_port: 8888              # 监听端口
jupyter_data: /data/jupyter     # 数据目录
jupyter_password: 'Jupyter.Lab' # 登录 Token
jupyter_venv: /data/venv        # Python 虚拟环境路径

Python 虚拟环境

JupyterLab 运行在 Python 虚拟环境中,需要预先创建:

# 创建虚拟环境
python3 -m venv /data/venv

# 安装 JupyterLab(VIBE 剧本会自动安装)
/data/venv/bin/pip install jupyterlab ipykernel

配置示例

# 自定义 JupyterLab 配置
jupyter_enabled: true
jupyter_password: 'MySecretToken'
jupyter_port: 8888
jupyter_data: /data/jupyter
jupyter_venv: /data/venv

Claude Code 配置

基本配置

claude_enabled: true   # 启用 Claude Code
claude_env: {}         # 额外环境变量

配置 API Key

Claude Code 需要 API Key 才能使用。可以通过 claude_env 传递:

claude_enabled: true
claude_env:
  ANTHROPIC_API_KEY: sk-ant-xxx-your-api-key

或者在部署后手动配置:

# 设置环境变量
export ANTHROPIC_API_KEY=sk-ant-xxx-your-api-key

# 或使用 Claude Code 配置命令
claude config set apiKey sk-ant-xxx-your-api-key

OpenTelemetry 配置

Claude Code 默认集成了 OpenTelemetry 可观测性,自动将指标和日志推送到 VictoriaMetrics/VictoriaLogs:

  • 指标端点http://127.0.0.1:8428/opentelemetry/v1/metrics
  • 日志端点http://127.0.0.1:9428/insert/opentelemetry/v1/logs

配置文件位于 ~/.claude/settings.json


工作目录配置

vibe_data 参数指定所有 VIBE 组件的共享工作目录:

vibe_data: /fs   # 默认使用 JuiceFS 挂载点

该目录用于:

  • Code-Server 的默认打开目录
  • JupyterLab 的 Notebook 根目录
  • Claude Code 的工作目录

建议配合 JuiceFS 使用,以获得:

  • 分布式文件系统的高可用
  • 基于 PostgreSQL 的 PITR 能力
  • 多节点间的文件共享

完整配置示例

最小配置

all:
  children:
    infra:
      hosts:
        10.10.10.10:
          code_enabled: true

标准配置

all:
  children:
    infra:
      hosts:
        10.10.10.10:
          # 工作目录
          vibe_data: /fs

          # Code-Server
          code_enabled: true
          code_port: 8443
          code_password: 'Code.Server'
          code_gallery: openvsx

          # JupyterLab
          jupyter_enabled: true
          jupyter_port: 8888
          jupyter_password: 'Jupyter.Lab'
          jupyter_venv: /data/venv

          # Claude Code
          claude_enabled: true
          claude_env:
            ANTHROPIC_API_KEY: sk-ant-xxx

AI 编程沙箱配置

完整的 AI 编程沙箱配置,包含 JuiceFS 共享存储:

all:
  vars:
    version: v3.4.0
    admin_ip: 10.10.10.10
    infra_portal:
      home: { domain: h.pigsty }
      grafana: { domain: g.pigsty, endpoint: "${admin_ip}:3000" }
      prometheus: { domain: p.pigsty, endpoint: "${admin_ip}:9090" }
      alertmanager: { domain: a.pigsty, endpoint: "${admin_ip}:9093" }
      code: { domain: code.pigsty, endpoint: "127.0.0.1:8443", websocket: true }
      jupyter: { domain: jupyter.pigsty, endpoint: "127.0.0.1:8888", websocket: true }

    # PostgreSQL 配置
    pg_cluster: pg-meta
    pg_databases:
      - name: meta

    # JuiceFS 配置
    juice_instances:
      jfs:
        path: /fs
        meta: postgres://dbuser_meta:DBUser.Meta@10.10.10.10:5432/meta
        data: --storage postgres --bucket postgres://dbuser_meta:DBUser.Meta@10.10.10.10:5432/meta?prefix=juice

  children:
    infra:
      hosts:
        10.10.10.10:
          # VIBE 配置
          vibe_data: /fs
          code_enabled: true
          code_password: 'YourSecurePassword'
          jupyter_enabled: true
          jupyter_password: 'YourSecureToken'
          claude_enabled: true
          claude_env:
            ANTHROPIC_API_KEY: sk-ant-xxx

禁用组件

如果不需要某个组件,可以将其禁用:

# 只启用 Code-Server
code_enabled: true
jupyter_enabled: false
claude_enabled: false

# 只启用 JupyterLab
code_enabled: false
jupyter_enabled: true
claude_enabled: false

# 只启用 Claude Code
code_enabled: false
jupyter_enabled: false
claude_enabled: true

或在执行剧本时通过命令行禁用:

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

Nginx 反向代理

VIBE 组件通过 Nginx 反向代理暴露到外部。相关配置在 infra_portal 中:

infra_portal:
  # 子路径方式(默认)
  home: { domain: h.pigsty }

  # 子域名方式(可选)
  code: { domain: code.pigsty, endpoint: "127.0.0.1:8443", websocket: true }
  jupyter: { domain: jupyter.pigsty, endpoint: "127.0.0.1:8888", websocket: true }

访问方式:

  • 子路径https://h.pigsty/code/https://h.pigsty/jupyter/
  • 子域名https://code.pigstyhttps://jupyter.pigsty

2 - VIBE 参数

VIBE 模块的配置参数详解,涵盖 Code-Server、JupyterLab 和 Claude Code 的所有可配置项。

VIBE 模块共有 13 个配置参数,分为三组:通用参数、Code-Server 参数、JupyterLab 参数和 Claude Code 参数。


参数概览

参数类型级别默认值说明
vibe_datapathH/I/fsVIBE 工作目录
code_enabledboolH/Itrue是否启用 Code-Server
code_portportH/I8443Code-Server 监听端口
code_datapathH/I/data/codeCode-Server 数据目录
code_passwordstringH/ICode.ServerCode-Server 登录密码
code_galleryenumH/Iopenvsx扩展市场类型
jupyter_enabledboolH/Itrue是否启用 JupyterLab
jupyter_portportH/I8888JupyterLab 监听端口
jupyter_datapathH/I/data/jupyterJupyterLab 数据目录
jupyter_passwordstringH/IJupyter.LabJupyterLab 登录 Token
jupyter_venvpathH/I/data/venvPython 虚拟环境路径
claude_enabledboolH/Itrue是否启用 Claude Code
claude_envdictH/I{}Claude Code 额外环境变量

通用参数

vibe_data

VIBE 模块的工作目录,所有组件的默认工作路径。

  • 类型path
  • 级别:H/I(主机/实例)
  • 默认值/fs

该目录用于:

  • Code-Server 打开的默认目录
  • JupyterLab 的 Notebook 根目录
  • Claude Code 的工作目录
  • 存放 CLAUDE.mdAGENTS.md 上下文文件

建议使用 JuiceFS 挂载点,以获得分布式存储和 PITR 能力。

vibe_data: /fs              # 默认值,JuiceFS 挂载点
vibe_data: /home/dev/work   # 自定义工作目录

Code-Server 参数

code_enabled

是否在该节点启用 Code-Server。

  • 类型bool
  • 级别:H/I
  • 默认值true
code_enabled: true   # 启用(默认)
code_enabled: false  # 禁用

code_port

Code-Server 监听端口,仅绑定 localhost。

  • 类型port
  • 级别:H/I
  • 默认值8443

外部访问通过 Nginx 反向代理,无需直接暴露此端口。

code_port: 8443   # 默认端口
code_port: 9443   # 自定义端口

code_data

Code-Server 用户数据目录,存放扩展、用户设置等。

  • 类型path
  • 级别:H/I
  • 默认值/data/code

目录结构:

/data/code/
├── code-server/
│   ├── config.yaml      # 配置文件
│   ├── extensions/      # 已安装扩展
│   └── User/
│       └── settings.json # 用户设置
└── ...
code_data: /data/code      # 默认路径
code_data: /home/dev/code  # 自定义路径

code_password

Code-Server 登录密码。

  • 类型string
  • 级别:H/I
  • 默认值Code.Server
code_password: 'Code.Server'     # 默认密码(请修改)
code_password: 'MySecretPass!'   # 自定义密码

Code-Server 扩展市场类型。

  • 类型enum
  • 级别:H/I
  • 默认值openvsx
  • 可选值openvsxmicrosoft
选项说明
openvsxOpen VSX 开源市场(默认)
microsoft微软官方 VS Code 市场

中国大陆用户会自动使用清华镜像加速。

code_gallery: openvsx    # Open VSX(默认)
code_gallery: microsoft  # 微软官方市场

JupyterLab 参数

jupyter_enabled

是否在该节点启用 JupyterLab。

  • 类型bool
  • 级别:H/I
  • 默认值true
jupyter_enabled: true   # 启用(默认)
jupyter_enabled: false  # 禁用

jupyter_port

JupyterLab 监听端口。

  • 类型port
  • 级别:H/I
  • 默认值8888

JupyterLab 绑定到 0.0.0.0,但通常通过 Nginx 反向代理访问。

jupyter_port: 8888   # 默认端口
jupyter_port: 8899   # 自定义端口

jupyter_data

JupyterLab 数据目录,存放配置文件和内核信息。

  • 类型path
  • 级别:H/I
  • 默认值/data/jupyter

目录结构:

/data/jupyter/
├── jupyter_config.py   # JupyterLab 配置
└── kernels/            # Jupyter 内核
jupyter_data: /data/jupyter      # 默认路径
jupyter_data: /home/dev/jupyter  # 自定义路径

jupyter_password

JupyterLab 登录 Token。

  • 类型string
  • 级别:H/I
  • 默认值Jupyter.Lab
jupyter_password: 'Jupyter.Lab'   # 默认 Token(请修改)
jupyter_password: 'MySecretToken' # 自定义 Token

jupyter_venv

JupyterLab 所在的 Python 虚拟环境路径。

  • 类型path
  • 级别:H/I
  • 默认值/data/venv

目录结构:

/data/venv/
└── bin/
    ├── python
    ├── pip
    └── jupyter
jupyter_venv: /data/venv          # 默认路径
jupyter_venv: /home/dev/.venv     # 自定义路径

Claude Code 参数

claude_enabled

是否在该节点启用 Claude Code CLI 配置。

  • 类型bool
  • 级别:H/I
  • 默认值true
claude_enabled: true   # 启用(默认)
claude_enabled: false  # 禁用

claude_env

Claude Code 的额外环境变量,用于配置 API Key 等。

  • 类型dict
  • 级别:H/I
  • 默认值{}

常用环境变量:

变量说明
ANTHROPIC_API_KEYAnthropic API 密钥
ANTHROPIC_BASE_URL自定义 API 端点
# 配置 API Key
claude_env:
  ANTHROPIC_API_KEY: sk-ant-xxx-your-api-key

# 配置自定义 API 端点
claude_env:
  ANTHROPIC_API_KEY: sk-ant-xxx
  ANTHROPIC_BASE_URL: https://api.example.com

参数级别说明

级别说明
G全局参数,在 all.vars 中定义
C集群参数,在集群层级定义
I实例参数,在主机层级定义
H主机参数,特指单个主机

VIBE 模块参数均为 H/I 级别,即在主机或实例层级定义。可以为不同主机配置不同的值:

all:
  children:
    infra:
      hosts:
        10.10.10.10:
          code_enabled: true
          code_password: 'Password1'
        10.10.10.11:
          code_enabled: true
          code_password: 'Password2'

默认值汇总

# VIBE 通用参数
vibe_data: /fs

# Code-Server 参数
code_enabled: true
code_port: 8443
code_data: /data/code
code_password: 'Code.Server'
code_gallery: openvsx

# JupyterLab 参数
jupyter_enabled: true
jupyter_port: 8888
jupyter_data: /data/jupyter
jupyter_password: 'Jupyter.Lab'
jupyter_venv: /data/venv

# Claude Code 参数
claude_enabled: true
claude_env: {}

3 - VIBE 剧本

VIBE 模块的 Ansible 剧本使用说明,包括部署、更新和管理操作。

VIBE 模块提供了一个主剧本 vibe.yml,用于部署和管理 Code-Server、JupyterLab 和 Claude Code。


剧本概览

剧本说明
vibe.yml在目标节点上部署 VIBE 开发环境(Code、Jupyter、Claude)

vibe.yml

vibe.yml 剧本用于在已纳管的节点上部署 VIBE 模块。

剧本内容

- name: Deploy VIBE development environment
  hosts: all
  become: yes
  gather_facts: no
  roles:
    - { role: node_id, tags: id }
    - { role: vibe, tags: vibe }

使用方法

# 完整部署(所有组件)
./vibe.yml -l <host>

# 仅部署 Code-Server
./vibe.yml -l <host> -t code

# 仅部署 JupyterLab
./vibe.yml -l <host> -t jupyter

# 仅部署 Claude Code
./vibe.yml -l <host> -t claude

# 禁用特定组件
./vibe.yml -l <host> -e code_enabled=false
./vibe.yml -l <host> -e jupyter_enabled=false
./vibe.yml -l <host> -e claude_enabled=false

# 配置 Claude API Key
./vibe.yml -l <host> -e claude_env.ANTHROPIC_API_KEY=sk-ant-xxx

任务结构

vibe.yml 剧本包含以下任务层级:

vibe
├── vibe_dir          # 创建工作目录并渲染上下文文件
├── claude            # 配置 Claude Code CLI
│   ├── claude_install    # 安装 claude 软件包
│   └── claude_config     # 渲染配置文件
├── code              # 部署 Code-Server
│   ├── code_install      # 安装 code-server 软件包
│   ├── code_dir          # 创建数据目录
│   ├── code_config       # 渲染配置文件和 systemd 服务单元
│   └── code_launch       # 启动 code-server 服务
└── jupyter           # 部署 JupyterLab
    ├── jupyter_install   # 安装 JupyterLab 到 venv
    ├── jupyter_dir       # 创建数据目录
    ├── jupyter_config    # 渲染配置文件和 systemd 服务单元
    └── jupyter_launch    # 启动 JupyterLab 服务

任务详解

vibe_dir

创建 VIBE 工作目录并渲染上下文文件。

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

执行内容:

  • 创建 {{ vibe_data }} 目录(默认 /fs
  • 渲染 CLAUDE.md 环境文档
  • 创建 AGENTS.md 符号链接

claude

配置 Claude Code CLI。

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

子任务:

标签说明
claude_install安装 claude 软件包
claude_config渲染 ~/.claude.json~/.claude/settings.json

配置文件内容:

  • ~/.claude.json:跳过新手引导对话框
  • ~/.claude/settings.json:OpenTelemetry 配置

code

部署 Code-Server。

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

子任务:

标签说明
code_install安装 code-server 软件包
code_dir创建 {{ code_data }} 数据目录
code_config渲染 config.yaml、systemd 服务单元、环境文件
code_launch启动/重启 code-server 服务

生成的文件:

  • /etc/systemd/system/code-server.service
  • /etc/default/code
  • {{ code_data }}/code-server/config.yaml

jupyter

部署 JupyterLab。

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

子任务:

标签说明
jupyter_install安装 JupyterLab 到 Python venv
jupyter_dir创建 {{ jupyter_data }} 数据目录
jupyter_config渲染 jupyter_config.py、systemd 服务单元、环境文件
jupyter_launch启动/重启 JupyterLab 服务

生成的文件:

  • /etc/systemd/system/jupyter.service
  • /etc/default/jupyter
  • {{ jupyter_data }}/jupyter_config.py

常用命令

完整部署

# 在单个主机上部署
./vibe.yml -l 10.10.10.10

# 在多个主机上部署
./vibe.yml -l '10.10.10.10,10.10.10.11'

# 在指定组上部署
./vibe.yml -l infra

组件级部署

# 仅部署 Code-Server
./vibe.yml -l <host> -t code

# 仅部署 JupyterLab
./vibe.yml -l <host> -t jupyter

# 仅部署 Claude Code
./vibe.yml -l <host> -t claude

配置更新

# 更新 Code-Server 配置并重启
./vibe.yml -l <host> -t code_config,code_launch

# 更新 JupyterLab 配置并重启
./vibe.yml -l <host> -t jupyter_config,jupyter_launch

# 更新 Claude Code 配置
./vibe.yml -l <host> -t claude_config

仅重启服务

# 重启 Code-Server
./vibe.yml -l <host> -t code_launch

# 重启 JupyterLab
./vibe.yml -l <host> -t jupyter_launch

参数覆盖

# 自定义密码
./vibe.yml -l <host> -e code_password='MyPassword'
./vibe.yml -l <host> -e jupyter_password='MyToken'

# 禁用组件
./vibe.yml -l <host> -e code_enabled=false
./vibe.yml -l <host> -e jupyter_enabled=false
./vibe.yml -l <host> -e claude_enabled=false

# 配置 Claude API Key
./vibe.yml -l <host> -e "claude_env={ANTHROPIC_API_KEY: 'sk-ant-xxx'}"

# 使用微软扩展市场
./vibe.yml -l <host> -e code_gallery=microsoft

部署顺序

VIBE 模块依赖于以下组件,请按顺序部署:

# 1. 部署基础设施(INFRA 模块)
./infra.yml

# 2. 部署 PostgreSQL(PGSQL 模块)
./pgsql.yml

# 3. 部署 JuiceFS 共享存储(可选,JUICE 模块)
./juice.yml

# 4. 部署 VIBE 开发环境
./vibe.yml

或使用一键部署:

./deploy.yml  # 包含 INFRA + PGSQL
./juice.yml   # JuiceFS(可选)
./vibe.yml    # VIBE

幂等性

VIBE 剧本支持幂等执行:

  • 可重复执行:多次执行不会产生副作用
  • 增量更新:只更新变化的配置
  • 服务重启:配置变更后自动重启相关服务
# 首次部署
./vibe.yml -l <host>

# 修改配置后重新执行(安全)
./vibe.yml -l <host>

执行保护

限制目标主机

使用 -l 参数限制执行范围:

# 仅在指定主机执行
./vibe.yml -l 10.10.10.10

# 仅在指定组执行
./vibe.yml -l infra

预览模式

使用 --check 参数预览变更:

./vibe.yml -l <host> --check

详细输出

使用 -v 参数查看详细输出:

./vibe.yml -l <host> -v      # 详细
./vibe.yml -l <host> -vv     # 更详细
./vibe.yml -l <host> -vvv    # 调试级别

4 - VIBE 管理

VIBE 模块的日常管理和运维操作指南,包括服务管理、密码修改、扩展安装等。

本文档介绍 VIBE 模块的日常管理操作,包括服务管理、配置修改、扩展安装等常用 SOP。


服务管理

Code-Server 服务

# 查看服务状态
sudo systemctl status code-server

# 启动服务
sudo systemctl start code-server

# 停止服务
sudo systemctl stop code-server

# 重启服务
sudo systemctl restart code-server

# 开机自启
sudo systemctl enable code-server

# 禁用自启
sudo systemctl disable code-server

JupyterLab 服务

# 查看服务状态
sudo systemctl status jupyter

# 启动服务
sudo systemctl start jupyter

# 停止服务
sudo systemctl stop jupyter

# 重启服务
sudo systemctl restart jupyter

# 开机自启
sudo systemctl enable jupyter

# 禁用自启
sudo systemctl disable jupyter

查看服务日志

# Code-Server 日志
journalctl -u code-server -f

# JupyterLab 日志
journalctl -u jupyter -f

# 查看最近 100 行日志
journalctl -u code-server -n 100
journalctl -u jupyter -n 100

密码管理

修改 Code-Server 密码

方法一:修改配置文件

# 编辑配置文件
sudo vi /data/code/code-server/config.yaml

# 修改 password 字段
password: YourNewPassword

# 重启服务
sudo systemctl restart code-server

方法二:使用 Ansible

# 修改 pigsty.yml 中的 code_password
# 然后执行
./vibe.yml -l <host> -t code_config,code_launch

修改 JupyterLab Token

方法一:修改配置文件

# 编辑配置文件
sudo vi /data/jupyter/jupyter_config.py

# 修改 c.ServerApp.token 值
c.ServerApp.token = 'YourNewToken'

# 重启服务
sudo systemctl restart jupyter

方法二:使用 Ansible

# 修改 pigsty.yml 中的 jupyter_password
# 然后执行
./vibe.yml -l <host> -t jupyter_config,jupyter_launch

扩展管理

Code-Server 扩展

通过 Web 界面安装

  1. 打开 Code-Server(https://<host>/code/
  2. 点击左侧扩展图标
  3. 搜索并安装所需扩展

通过命令行安装

# 安装单个扩展
code-server --install-extension ms-python.python

# 从 VSIX 文件安装
code-server --install-extension /path/to/extension.vsix

# 列出已安装扩展
code-server --list-extensions

# 卸载扩展
code-server --uninstall-extension ms-python.python

切换扩展市场

修改 code_gallery 参数:

# Open VSX(默认)
code_gallery: openvsx

# 微软官方市场
code_gallery: microsoft

然后重新部署:

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

JupyterLab 扩展

安装 JupyterLab 扩展

# 激活虚拟环境
source /data/venv/bin/activate

# 安装扩展
pip install jupyterlab-git
pip install jupyterlab-lsp

# 重启 JupyterLab
sudo systemctl restart jupyter

Python 包管理

安装 Python 包

# 激活虚拟环境
source /data/venv/bin/activate

# 使用 pip 安装
pip install numpy pandas matplotlib scikit-learn

# 使用清华镜像加速
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple numpy pandas

# 使用 uv 安装(更快)
uv pip install numpy pandas matplotlib

配置 pip 镜像

# 临时使用
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple <package>

# 永久配置
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

安装 Jupyter Kernel

# 安装 ipykernel
pip install ipykernel

# 注册新内核
python -m ipykernel install --user --name myenv --display-name "Python (myenv)"

# 列出已注册内核
jupyter kernelspec list

# 删除内核
jupyter kernelspec remove myenv

Claude Code 管理

配置 API Key

方法一:环境变量

# 临时设置
export ANTHROPIC_API_KEY=sk-ant-xxx-your-api-key

# 永久设置(添加到 ~/.bashrc 或 ~/.zshrc)
echo 'export ANTHROPIC_API_KEY=sk-ant-xxx-your-api-key' >> ~/.bashrc
source ~/.bashrc

方法二:Claude 配置命令

claude config set apiKey sk-ant-xxx-your-api-key

方法三:Ansible 部署时配置

claude_env:
  ANTHROPIC_API_KEY: sk-ant-xxx-your-api-key

查看 Claude 配置

# 查看当前配置
cat ~/.claude.json
cat ~/.claude/settings.json

# 查看 Claude 版本
claude --version

使用 Claude Code

# 在当前目录启动 Claude
claude

# 在指定目录启动
claude /path/to/project

# 非交互模式执行任务
claude -p "解释这段代码的作用"

# 指定模型
claude --model claude-sonnet-4-20250514

目录结构

VIBE 工作目录

{{ vibe_data }}           # 默认 /fs
├── CLAUDE.md             # Claude Code 上下文文件
├── AGENTS.md             # 符号链接 -> CLAUDE.md
└── <your-projects>/      # 项目文件

Code-Server 数据目录

{{ code_data }}           # 默认 /data/code
└── code-server/
    ├── config.yaml       # 配置文件
    ├── extensions/       # 扩展目录
    └── User/
        └── settings.json # 用户设置

JupyterLab 数据目录

{{ jupyter_data }}        # 默认 /data/jupyter
├── jupyter_config.py     # 配置文件
└── kernels/              # Jupyter 内核

Python 虚拟环境

{{ jupyter_venv }}        # 默认 /data/venv
├── bin/
│   ├── python
│   ├── pip
│   ├── jupyter
│   └── ...
├── lib/
│   └── python3.x/
│       └── site-packages/
└── ...

配置文件位置

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

连接 PostgreSQL

从 JupyterLab 连接

import psycopg2

# 连接数据库
conn = psycopg2.connect(
    'postgres://dbuser_dba:DBUser.DBA@10.10.10.10:5432/meta'
)
cursor = conn.cursor()

# 执行查询
cursor.execute('SELECT version()')
print(cursor.fetchone())

# 关闭连接
cursor.close()
conn.close()

使用 pandas

import pandas as pd
import psycopg2

conn = psycopg2.connect(
    'postgres://dbuser_dba:DBUser.DBA@10.10.10.10:5432/meta'
)
df = pd.read_sql('SELECT * FROM pg_stat_activity', conn)
df.head()

从 Code-Server 终端连接

# 使用 psql
psql postgres://dbuser_dba:DBUser.DBA@10.10.10.10:5432/meta

# 使用 pgcli(如已安装)
pgcli postgres://dbuser_dba:DBUser.DBA@10.10.10.10:5432/meta

备份与恢复

备份 Code-Server 配置

# 备份用户数据
tar -czvf code-backup.tar.gz /data/code

# 恢复
tar -xzvf code-backup.tar.gz -C /
sudo systemctl restart code-server

备份 JupyterLab 配置

# 备份配置和 Notebook
tar -czvf jupyter-backup.tar.gz /data/jupyter /fs/*.ipynb

# 恢复
tar -xzvf jupyter-backup.tar.gz -C /
sudo systemctl restart jupyter

使用 JuiceFS PITR

如果工作目录使用 JuiceFS,可以利用 PostgreSQL 的 PITR 能力进行时间点恢复。详见 JUICE 管理文档


故障排查

服务无法启动

# 查看详细错误日志
journalctl -u code-server -xe
journalctl -u jupyter -xe

# 检查端口占用
ss -tlnp | grep 8443
ss -tlnp | grep 8888

# 检查进程
ps aux | grep code-server
ps aux | grep jupyter

无法访问 Web 界面

# 检查 Nginx 状态
sudo systemctl status nginx

# 检查 Nginx 配置
sudo nginx -t

# 检查防火墙
sudo firewall-cmd --list-all

JupyterLab Python 版本问题

# 检查 venv 中的 Python 版本
/data/venv/bin/python --version

# 检查 JupyterLab 版本
/data/venv/bin/jupyter --version

# 重建虚拟环境
rm -rf /data/venv
python3 -m venv /data/venv
/data/venv/bin/pip install jupyterlab ipykernel

5 - VIBE 监控

VIBE 模块的监控集成说明,包括 Claude Code 可观测性、Dashboard 使用等。

VIBE 模块提供了完整的可观测性支持,特别是 Claude Code 的 OpenTelemetry 集成,可以通过 Grafana Dashboard 监控 AI 编程助手的使用情况。


监控架构

Claude Code CLI
    │
    ├── OpenTelemetry Metrics ──► VictoriaMetrics (8428)
    └── OpenTelemetry Logs    ──► VictoriaLogs    (9428)
                                       │
                                       ▼
                               Grafana Dashboard
                               (Claude Code Dashboard)

Claude Code 可观测性

OpenTelemetry 配置

Claude Code 默认集成了 OpenTelemetry,自动将指标和日志推送到本地的 VictoriaMetrics/VictoriaLogs:

配置文件 ~/.claude/settings.json

{
  "otelEndpointMetrics": "http://127.0.0.1:8428/opentelemetry/v1/metrics",
  "otelEndpointLogs": "http://127.0.0.1:9428/insert/opentelemetry/v1/logs",
  "otelResourceAttributes": {
    "ip": "10.10.10.10",
    "job": "claude"
  }
}

监控指标

Claude Code 上报的主要指标包括:

指标类型说明
会话指标会话数量、持续时间
Token 指标输入/输出 Token 数量、成本统计
API 调用API 请求次数、延迟、错误率
工具使用各类工具(Read、Write、Bash 等)调用次数

日志数据

Claude Code 的日志包含:

  • 会话开始/结束事件
  • 用户提示和助手响应
  • 工具调用详情
  • 错误和警告信息

Grafana Dashboard

访问 Dashboard

Claude Code Dashboard 可以通过以下方式访问:

https://<ip>:3000/d/claude-code

使用 Grafana 凭证登录(默认:admin / pigsty)。

Dashboard 功能

面板说明
会话概览活跃会话数、总会话数
Token 使用输入/输出 Token 趋势、成本分析
API 性能请求延迟、错误率
工具使用统计各工具调用频次、耗时分布
会话日志详细的会话记录和对话内容

系统服务监控

使用 systemd 监控

# 查看 Code-Server 状态
systemctl status code-server

# 查看 JupyterLab 状态
systemctl status jupyter

# 查看服务日志
journalctl -u code-server -f
journalctl -u jupyter -f

端口检查

# 检查 Code-Server 端口(8443)
ss -tlnp | grep 8443

# 检查 JupyterLab 端口(8888)
ss -tlnp | grep 8888

# 使用 curl 检查服务
curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:8443
curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:8888

健康检查

自动化健康检查脚本

#!/bin/bash
# vibe-health-check.sh

echo "=== VIBE 服务健康检查 ==="

# Code-Server
if systemctl is-active --quiet code-server; then
    echo "[OK] Code-Server: 运行中"
else
    echo "[ERROR] Code-Server: 未运行"
fi

# JupyterLab
if systemctl is-active --quiet jupyter; then
    echo "[OK] JupyterLab: 运行中"
else
    echo "[ERROR] JupyterLab: 未运行"
fi

# 端口检查
if ss -tlnp | grep -q ":8443 "; then
    echo "[OK] Code-Server 端口 8443: 监听中"
else
    echo "[ERROR] Code-Server 端口 8443: 未监听"
fi

if ss -tlnp | grep -q ":8888 "; then
    echo "[OK] JupyterLab 端口 8888: 监听中"
else
    echo "[ERROR] JupyterLab 端口 8888: 未监听"
fi

使用 curl 进行端点检查

# 检查 Code-Server
curl -s -o /dev/null -w "%{http_code}\n" \
    --connect-timeout 5 \
    http://127.0.0.1:8443/healthz

# 检查 JupyterLab
curl -s -o /dev/null -w "%{http_code}\n" \
    --connect-timeout 5 \
    http://127.0.0.1:8888/api/status

告警配置

服务停止告警

可以在 Alertmanager 中配置 VIBE 服务告警:

# 示例:Code-Server 停止告警
- alert: CodeServerDown
  expr: up{job="code-server"} == 0
  for: 5m
  labels:
    severity: warning
  annotations:
    summary: "Code-Server 服务停止"
    description: "Code-Server 在 {{ $labels.instance }} 上已停止超过 5 分钟"

# 示例:JupyterLab 停止告警
- alert: JupyterLabDown
  expr: up{job="jupyter"} == 0
  for: 5m
  labels:
    severity: warning
  annotations:
    summary: "JupyterLab 服务停止"
    description: "JupyterLab 在 {{ $labels.instance }} 上已停止超过 5 分钟"

日志管理

日志位置

组件日志位置
Code-Serverjournalctl -u code-server
JupyterLabjournalctl -u jupyter
Claude CodeVictoriaLogs / ~/.claude/logs/

日志查询

使用 journalctl

# 查看最近日志
journalctl -u code-server -n 100

# 查看特定时间范围
journalctl -u code-server --since "2024-01-01" --until "2024-01-02"

# 实时跟踪
journalctl -u code-server -f

使用 VictoriaLogs 查询 Claude 日志

# 通过 Grafana Explore 面板查询
# 或使用 vlogs API
curl -G 'http://localhost:9428/select/logsql/query' \
    --data-urlencode 'query={job="claude"}'

资源监控

查看资源使用

# 查看 Code-Server 资源使用
systemctl status code-server
ps aux | grep code-server

# 查看 JupyterLab 资源使用
systemctl status jupyter
ps aux | grep jupyter

# 查看内存使用
free -h

# 查看磁盘使用
df -h /data
df -h /fs

JuiceFS 存储监控

如果使用 JuiceFS 作为工作目录:

# 查看 JuiceFS 状态
juicefs status /fs

# 查看文件系统使用情况
df -h /fs

# 查看文件统计
juicefs info /fs

性能调优

Code-Server 性能优化

# 增加文件句柄限制(已在 systemd 服务中配置)
# /etc/systemd/system/code-server.service
LimitNOFILE=65535

JupyterLab 性能优化

# /data/jupyter/jupyter_config.py

# 增加最大缓冲区大小
c.ServerApp.max_buffer_size = 1073741824  # 1GB

# 配置超时时间
c.ServerApp.shutdown_no_activity_timeout = 0  # 禁用自动关闭

6 - VIBE FAQ

VIBE 模块的常见问题解答,涵盖部署、配置、使用等方面的常见问题。

本文档汇总了 VIBE 模块使用过程中的常见问题和解决方案。


部署问题

如何使用 VIBE 配置模板?

# 下载 Pigsty
curl https://repo.pigsty.io/get | bash

# 使用 vibe 配置模板
./configure -c vibe

# 修改密码后部署
vi pigsty.yml
./deploy.yml
./juice.yml   # 可选
./vibe.yml

部署时报错 “code-server package not found”

确保已正确配置软件仓库:

# 检查仓库是否可用
yum repolist          # EL 系统
apt update            # Debian/Ubuntu

# 重新刷新仓库缓存
./infra.yml -t repo

JupyterLab 安装失败

检查 Python 虚拟环境是否存在:

# 检查 venv
ls -la /data/venv/bin/python

# 如不存在,手动创建
python3 -m venv /data/venv

# 重新执行剧本
./vibe.yml -l <host> -t jupyter

访问问题

无法访问 Code-Server

  1. 检查服务状态

    systemctl status code-server
    
  2. 检查端口监听

    ss -tlnp | grep 8443
    
  3. 检查 Nginx 配置

    nginx -t
    systemctl status nginx
    
  4. 检查防火墙

    firewall-cmd --list-all
    

无法访问 JupyterLab

  1. 检查服务状态

    systemctl status jupyter
    
  2. 检查端口监听

    ss -tlnp | grep 8888
    
  3. 验证 Token

    确保使用正确的 Token 访问,默认为 Jupyter.Lab

WebSocket 连接失败

JupyterLab 和 Code-Server 都依赖 WebSocket。确保 Nginx 配置正确:

proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

检查 infra_portal 配置是否启用了 WebSocket:

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 }

密码和认证

如何修改 Code-Server 密码?

方法一:直接修改配置

vi /data/code/code-server/config.yaml
# 修改 password 字段
systemctl restart code-server

方法二:使用 Ansible

# 修改 pigsty.yml 中的 code_password
./vibe.yml -l <host> -t code_config,code_launch

如何修改 JupyterLab Token?

方法一:直接修改配置

vi /data/jupyter/jupyter_config.py
# 修改 c.ServerApp.token
systemctl restart jupyter

方法二:使用 Ansible

# 修改 pigsty.yml 中的 jupyter_password
./vibe.yml -l <host> -t jupyter_config,jupyter_launch

忘记密码怎么办?

查看配置文件中的密码:

# Code-Server 密码
grep password /data/code/code-server/config.yaml

# JupyterLab Token
grep token /data/jupyter/jupyter_config.py

Claude Code 问题

Claude Code 无法使用

  1. 检查 API Key 是否配置

    echo $ANTHROPIC_API_KEY
    cat ~/.claude.json
    
  2. 配置 API Key

    export ANTHROPIC_API_KEY=sk-ant-xxx
    # 或
    claude config set apiKey sk-ant-xxx
    

Claude Code 无法连接 API

  1. 检查网络

    curl -I https://api.anthropic.com
    
  2. 检查代理设置

    echo $HTTP_PROXY
    echo $HTTPS_PROXY
    

Claude Code 监控数据不显示

检查 OpenTelemetry 端点是否可达:

# 检查 VictoriaMetrics
curl http://127.0.0.1:8428/api/v1/status/buildinfo

# 检查 VictoriaLogs
curl http://127.0.0.1:9428/select/logsql/stats_query

确认 ~/.claude/settings.json 配置正确。


扩展和插件

Code-Server 扩展安装失败

  1. 检查网络连接

    curl -I https://open-vsx.org
    
  2. 切换扩展市场

    code_gallery: microsoft  # 切换到微软市场
    

    重新部署:

    ./vibe.yml -l <host> -t code_config,code_launch
    
  3. 手动安装 VSIX

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

如何使用 GitHub Copilot?

GitHub Copilot 不支持 Code-Server。可以考虑:

  • 使用 Claude Code 作为 AI 编程助手
  • 使用 Codeium 等支持 Code-Server 的 AI 工具

JupyterLab 扩展安装失败

# 激活虚拟环境
source /data/venv/bin/activate

# 检查 JupyterLab 版本
jupyter --version

# 安装扩展
pip install jupyterlab-git

# 重启服务
systemctl restart jupyter

Python 和 Jupyter

JupyterLab 无法启动

  1. 检查虚拟环境

    /data/venv/bin/python --version
    /data/venv/bin/jupyter --version
    
  2. 重新安装 JupyterLab

    /data/venv/bin/pip install --upgrade jupyterlab ipykernel
    
  3. 检查日志

    journalctl -u jupyter -xe
    

如何安装额外的 Python 包?

# 激活虚拟环境
source /data/venv/bin/activate

# 安装包
pip install numpy pandas matplotlib

# 使用清华镜像
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple numpy pandas

如何添加新的 Jupyter Kernel?

# 安装 ipykernel
pip install ipykernel

# 注册内核
python -m ipykernel install --user --name myenv --display-name "Python (myenv)"

# 列出内核
jupyter kernelspec list

如何连接 PostgreSQL?

import psycopg2

conn = psycopg2.connect(
    'postgres://dbuser_dba:DBUser.DBA@10.10.10.10:5432/meta'
)
cursor = conn.cursor()
cursor.execute('SELECT version()')
print(cursor.fetchone())
conn.close()

性能和资源

Code-Server 卡顿

  1. 检查内存使用

    free -h
    ps aux | grep code-server
    
  2. 禁用不必要的扩展

    在 Code-Server 中禁用不常用的扩展。

  3. 增加系统资源

    考虑增加虚拟机内存。

JupyterLab Notebook 运行缓慢

  1. 检查内核资源

    top
    htop
    
  2. 清理 Notebook 输出

    清除 Cell 输出可以减少内存占用。

  3. 重启内核

    定期重启内核释放内存。

磁盘空间不足

# 检查磁盘使用
df -h

# 清理日志
journalctl --vacuum-time=7d

# 清理 pip 缓存
pip cache purge

JuiceFS 集成

工作目录不可用

  1. 检查 JuiceFS 挂载

    mount | grep juicefs
    df -h /fs
    
  2. 重新挂载

    ./juice.yml -l <host>
    

文件系统性能差

  1. 检查网络延迟

    ping <postgresql-host>
    
  2. 检查 PostgreSQL 状态

    psql postgres://... -c "SELECT 1"
    

安全问题

如何限制访问?

  1. 配置防火墙

    # 只允许特定 IP
    firewall-cmd --add-rich-rule='rule family="ipv4" source address="10.0.0.0/8" port port="443" protocol="tcp" accept'
    
  2. 使用 Nginx 访问控制

    location /code/ {
        allow 10.0.0.0/8;
        deny all;
        ...
    }
    

默认密码是否安全?

不安全! 生产环境务必修改:

  • code_password:默认 Code.Server
  • jupyter_password:默认 Jupyter.Lab
code_password: 'YourStrongPassword!'
jupyter_password: 'YourStrongToken!'

支持平台

支持哪些操作系统?

系统版本
EL8、9、10
Ubuntu20.04、22.04、24.04
Debian11、12、13

支持哪些架构?

  • x86_64 (AMD64)
  • ARM64 (AArch64)

Ansible 版本要求?

最低版本:Ansible 2.9+