这是本节的多页打印视图。
点击此处打印.
返回本页常规视图.
模块: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 Code | Anthropic 的 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 配置模板:
2. 部署基础设施
./deploy.yml # 部署 INFRA + PGSQL
./juice.yml # 部署 JuiceFS 共享存储(可选)
3. 部署 VIBE 模块
./vibe.yml # 部署 Code-Server + JupyterLab + Claude Code
4. 访问服务
| 服务 | 地址 | 默认凭证 |
|---|
| Code-Server | https://<ip>/code/ | Code.Server |
| JupyterLab | https://<ip>/jupyter/ | Jupyter.Lab |
| Claude 监控 | https://<ip>:3000/d/claude-code | Grafana 凭证 |
配置示例
典型的 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 配置模板预装了以下开发工具:
| 工具 | 说明 |
|---|
claude | Anthropic Claude Code CLI |
opencode | 开源 AI 编程助手 |
code-server | 浏览器中的 VS Code |
golang | Go 语言工具链 |
nodejs | Node.js 运行时 |
uv | 高性能 Python 包管理器 |
postgrest | PostgreSQL RESTful API 服务 |
genai-toolbox | Google GenAI Toolbox MCP 服务 |
restic | 增量备份工具 |
rclone | 云存储同步工具 |
asciinema | 终端录屏工具 |
PostgreSQL 扩展
VIBE 配置模板的 PostgreSQL 预装了丰富的扩展:
- 向量搜索:
pgvector、pgvectorscale - 时序分析:
timescaledb、pg_timeseries - 地理空间:
postgis、h3、pgrouting - 数据分析:
pg_duckdb、pg_analytics、hydra - 全文搜索:
pg_search、zhparser - 安全增强:
pg_tde、supabase_vault、pgsodium - 更多扩展:详见 扩展目录
使用场景
- AI 辅助开发:利用 Claude Code 进行智能编程,提升开发效率
- 数据科学:JupyterLab + PostgreSQL + 向量/时序扩展,构建分析平台
- 远程开发:在任何设备上通过浏览器访问完整开发环境
- 教学培训:快速搭建标准化的教学环境,降低环境配置门槛
- 原型验证:快速搭建 PoC 环境,验证技术方案
注意事项
安全提醒
- 请务必修改默认密码(
code_password、jupyter_password) - 生产环境建议配置防火墙限制访问来源
- Claude Code 需要配置 API Key 才能使用
文档目录
- 配置说明:如何配置 VIBE 模块的各个组件
- 参数详解:VIBE 模块的所有配置参数
- 剧本说明:部署和管理 VIBE 的 Ansible 剧本
- 管理手册:日常管理和运维操作指南
- 监控集成:监控指标和 Dashboard 说明
- 常见问题:使用中的常见问题解答
1 - 配置 VIBE
VIBE 模块的配置说明,包括 Code-Server、JupyterLab 和 Claude Code 的详细配置方法。
VIBE 模块提供了灵活的配置选项,可以根据需求启用或禁用各个组件,并自定义其行为。
配置概览
VIBE 模块包含三个可独立配置的组件:
| 组件 | 启用参数 | 默认状态 | 说明 |
|---|
| Code-Server | code_enabled | 启用 | 浏览器中的 VS Code |
| JupyterLab | jupyter_enabled | 启用 | 交互式计算环境 |
| Claude Code | claude_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 支持多种扩展市场:
| 选项 | 说明 |
|---|
openvsx | Open 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.pigsty、https://jupyter.pigsty
2 - VIBE 参数
VIBE 模块的配置参数详解,涵盖 Code-Server、JupyterLab 和 Claude Code 的所有可配置项。
VIBE 模块共有 13 个配置参数,分为三组:通用参数、Code-Server 参数、JupyterLab 参数和 Claude Code 参数。
参数概览
通用参数
vibe_data
VIBE 模块的工作目录,所有组件的默认工作路径。
- 类型:
path - 级别:H/I(主机/实例)
- 默认值:
/fs
该目录用于:
- Code-Server 打开的默认目录
- JupyterLab 的 Notebook 根目录
- Claude Code 的工作目录
- 存放
CLAUDE.md 和 AGENTS.md 上下文文件
建议使用 JuiceFS 挂载点,以获得分布式存储和 PITR 能力。
vibe_data: /fs # 默认值,JuiceFS 挂载点
vibe_data: /home/dev/work # 自定义工作目录
Code-Server 参数
code_enabled
是否在该节点启用 Code-Server。
code_enabled: true # 启用(默认)
code_enabled: false # 禁用
code_port
Code-Server 监听端口,仅绑定 localhost。
外部访问通过 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_gallery
Code-Server 扩展市场类型。
- 类型:
enum - 级别:H/I
- 默认值:
openvsx - 可选值:
openvsx、microsoft
| 选项 | 说明 |
|---|
openvsx | Open VSX 开源市场(默认) |
microsoft | 微软官方 VS Code 市场 |
中国大陆用户会自动使用清华镜像加速。
code_gallery: openvsx # Open VSX(默认)
code_gallery: microsoft # 微软官方市场
JupyterLab 参数
jupyter_enabled
是否在该节点启用 JupyterLab。
jupyter_enabled: true # 启用(默认)
jupyter_enabled: false # 禁用
jupyter_port
JupyterLab 监听端口。
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 配置。
claude_enabled: true # 启用(默认)
claude_enabled: false # 禁用
claude_env
Claude Code 的额外环境变量,用于配置 API Key 等。
常用环境变量:
| 变量 | 说明 |
|---|
ANTHROPIC_API_KEY | Anthropic 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 界面安装
- 打开 Code-Server(
https://<host>/code/) - 点击左侧扩展图标
- 搜索并安装所需扩展
通过命令行安装
# 安装单个扩展
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-Server | journalctl -u code-server |
| JupyterLab | journalctl -u jupyter |
| Claude Code | VictoriaLogs / ~/.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
检查服务状态
systemctl status code-server
检查端口监听
检查 Nginx 配置
nginx -t
systemctl status nginx
检查防火墙
无法访问 JupyterLab
检查服务状态
检查端口监听
验证 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 无法使用
检查 API Key 是否配置
echo $ANTHROPIC_API_KEY
cat ~/.claude.json
配置 API Key
export ANTHROPIC_API_KEY=sk-ant-xxx
# 或
claude config set apiKey sk-ant-xxx
Claude Code 无法连接 API
检查网络
curl -I https://api.anthropic.com
检查代理设置
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 扩展安装失败
检查网络连接
curl -I https://open-vsx.org
切换扩展市场
code_gallery: microsoft # 切换到微软市场
重新部署:
./vibe.yml -l <host> -t code_config,code_launch
手动安装 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 无法启动
检查虚拟环境
/data/venv/bin/python --version
/data/venv/bin/jupyter --version
重新安装 JupyterLab
/data/venv/bin/pip install --upgrade jupyterlab ipykernel
检查日志
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 卡顿
检查内存使用
free -h
ps aux | grep code-server
禁用不必要的扩展
在 Code-Server 中禁用不常用的扩展。
增加系统资源
考虑增加虚拟机内存。
JupyterLab Notebook 运行缓慢
检查内核资源
清理 Notebook 输出
清除 Cell 输出可以减少内存占用。
重启内核
定期重启内核释放内存。
磁盘空间不足
# 检查磁盘使用
df -h
# 清理日志
journalctl --vacuum-time=7d
# 清理 pip 缓存
pip cache purge
JuiceFS 集成
工作目录不可用
检查 JuiceFS 挂载
mount | grep juicefs
df -h /fs
重新挂载
文件系统性能差
检查网络延迟
检查 PostgreSQL 状态
psql postgres://... -c "SELECT 1"
安全问题
如何限制访问?
配置防火墙
# 只允许特定 IP
firewall-cmd --add-rich-rule='rule family="ipv4" source address="10.0.0.0/8" port port="443" protocol="tcp" accept'
使用 Nginx 访问控制
location /code/ {
allow 10.0.0.0/8;
deny all;
...
}
默认密码是否安全?
不安全! 生产环境务必修改:
code_password:默认 Code.Serverjupyter_password:默认 Jupyter.Lab
code_password: 'YourStrongPassword!'
jupyter_password: 'YourStrongToken!'
支持平台
支持哪些操作系统?
| 系统 | 版本 |
|---|
| EL | 8、9、10 |
| Ubuntu | 20.04、22.04、24.04 |
| Debian | 11、12、13 |
支持哪些架构?
- x86_64 (AMD64)
- ARM64 (AArch64)
Ansible 版本要求?
最低版本:Ansible 2.9+