mcpField
O
ov-server-operate

ov-server-operate

github.com/volcengineクラウド・DevOps41.1k142 回インストール今日更新
リポジトリ

ov-server-operate について

本番環境で OpenViking サーバーをデプロイ、管理、保守するための運用ガイドです。設定、起動と停止、データのクリーンアップ、ヘルスチェック、トラブルシューティングの手順を説明します。

主な機能

  1. 01サーバーと CLI の設定ファイル作成
  2. 02uv による Python 環境の準備
  3. 03サーバーの起動と停止
  4. 04サーバーデータの安全な削除
  5. 05ヘルスチェックと問題の調査

活用シーン

  1. 01OpenViking の本番サーバーの準備
  2. 02サービスの再起動や停止
  3. 03起動や API キーのエラー調査
  4. 04サーバーの初期化やストレージ回収

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/volcengine/openviking --skill ov-server-operate

インストール後、Claude Code で/ov-server-operateを入力して読み込まれたか確認します。

詳細

OpenViking サーバーの運用

このガイドでは、本番環境で OpenViking サーバーをデプロイ、管理、保守するための標準的な運用手順を説明します。

目次

  • サービスの設定
  • uv を使った環境構築
  • nohup を使ったサーバーの起動
  • サーバーの停止
  • データのクリーンアップ手順
  • 検証とトラブルシューティング

サービスの設定

デフォルトのパスと構成

OpenViking は ~/.openviking/ 以下に、次の標準ディレクトリ構成を使用します。

~/.openviking/
├── ov.conf             # Server configuration (required)
├── ovcli.conf          # CLI client configuration
├── ov-venv/            # Virtual environment (created by uv)
├── log/                # Server log directory
│   ├── openviking-server.log   # server stdout log
│   └── openviking.log          # server log
└── data/               # Workspace data (configured in ov.conf)
    ├── ...
    └── ...
設定ファイル
1. サーバー設定（~/.openviking/ov.conf）

最低限、次の設定を含む設定ファイルを作成します。 注 1：api-key をご自身の api-key に置き換えてください。お持ちでない場合は、ユーザーに取得を依頼してください（Volcengine Ark プラットフォームのガイドに従ってください）。 注 2：root_api_key をご自身の root-api-key に置き換えてください。ユーザーに設定を依頼してください。これは、CLI がサーバーに接続する際の認証に使用されます。

{
  "server": {
    "host": "0.0.0.0",
    "port": 1933,
    "root_api_key": "your-root-api-key"
  },
  "storage": {
    "workspace": "~/.openviking/data/"
  },
  "parsers": {
    "code": {
      "gitlab_domains": ["code.byted.org"],
      "azure_devops_domains": ["ssh.dev.azure.com", "vs-ssh.visualstudio.com"]
    }
  },
  "embedding": {
    "dense": {
        "model": "doubao-embedding-vision-251215",
        "api_key": "your-volcengine-api-key",
        "api_base": "https://ark.cn-beijing.volces.com/api/v3",
        "dimension": 1024,
        "input": "multimodal",
        "provider": "volcengine"
    }
  },
  "vlm": {
    "model": "doubao-seed-1-8-251228",
    "api_key": "your-volcengine-api-key",
    "api_base": "https://ark.cn-beijing.volces.com/api/v3",
    "temperature": 0.0,
    "max_retries": 2,
    "provider": "volcengine",
    "thinking": false
  },
  "log": {
    "level": "INFO",
    "output": "file",
    "rotation": true,
    "rotation_days": 3,
    "rotation_interval": "midnight"
  }
}
2. CLI 設定（~/.openviking/ovcli.conf）

localhost からクライアント接続する場合：

{
  "url": "http://localhost:1933",
  "api_key": "your-root-api-key"
}

リモート接続の場合は、url にリモートサーバーのアドレス（サーバーの EIP など）を設定します。

uv を使った環境構築

手順 1：uv をインストールする（未インストールの場合）
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Verify installation
uv --version
手順 2：仮想環境を作成する

~/.openviking/ov-venv に専用の仮想環境を作成します。

# Create venv with Python 3.10+
cd ~/.openviking
uv venv --python 3.12 ov-venv
手順 3：OpenViking を有効化してインストールする
# Activate the virtual environment
source ~/.openviking/ov-venv/bin/activate

# Install or upgrade to latest openviking
uv pip install --upgrade openviking --force-reinstall

# Verify installation
which openviking-server
openviking-server --version
openviking-server --help
手順 4：ログディレクトリを作成する
mkdir -p ~/.openviking/log

nohup を使ったサーバーの起動

標準的な起動手順
# 1. Activate the virtual environment
source ~/.openviking/ov-venv/bin/activate

# 2. Ensure log directory exists
mkdir -p ~/.openviking/log

# 3. Start server with nohup
nohup openviking-server \
    > ~/.openviking/log/openviking-server.log 2>&1 &

# 4. Save PID for later reference
echo $! > ~/.openviking/server.pid

# 5. Verify startup after 10 secs
sleep 10
curl -s http://localhost:1933/health
サーバーの稼働を確認する
# Method 1: Check health endpoint
curl http://localhost:1933/health
# Expected: {"status": "ok"}

# Method 2: Check readiness (includes storage checks)
curl http://localhost:1933/ready

# Method 3: Check process
ps aux | grep openviking-server | grep -v grep

# Method 4: Check log output
tail -10 ~/.openviking/log/openviking-server.log
tail -50 ~/.openviking/log/openviking.log

サーバーの停止

安全に停止する手順
# 1. Find the server process
ps aux | grep openviking-server | grep -v grep

# 2. Send SIGTERM for graceful shutdown
# Option A: Using saved PID
if [ -f ~/.openviking/server.pid ]; then
    kill $(cat ~/.openviking/server.pid)
    rm ~/.openviking/server.pid
fi

# Option B: Using pgrep
pkill -f openviking-server

# 3. Wait for process to stop
sleep 3

# 4. Verify it stopped
ps aux | grep openviking-server | grep -v grep || echo "Server stopped successfully"

# 5. If still running, force kill
if pgrep -f openviking-server > /dev/null; then
    echo "Force killing server..."
    pkill -9 -f openviking-server
fi

データのクリーンアップ手順

この手順を使用するタイミング

次のような場合は、データを完全にクリーンアップしてください。

  1. データ形式に互換性のないバージョンへアップグレードする場合
  2. データが破損している、または一貫性がない場合
  3. 初期状態にリセットする必要がある場合
  4. ストレージ領域を確保する場合
標準的なクリーンアップのワークフロー

重要：データを削除する前に、必ずバックアップしてください

# ==========================================
# STEP 1: STOP THE SERVER FIRST
# ==========================================
echo "Step 1: Stopping OpenViking Server..."
if pgrep -f openviking-server > /dev/null; then
    pkill -f openviking-server
    sleep 3
    if pgrep -f openviking-server > /dev/null; then
        pkill -9 -f openviking-server
        sleep 1
    fi
fi

# Verify server is stopped
if pgrep -f openviking-server > /dev/null; then
    echo "ERROR: Server still running! Cannot proceed."
    exit 1
fi
echo "✓ Server stopped"

# ==========================================
# STEP 2: CREATE BACKUP (REQUIRED)
# ==========================================
echo ""
echo "Step 2: Creating backup..."
BACKUP_DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR=~/.openviking/backup_${BACKUP_DATE}

mkdir -p ${BACKUP_DIR}

# Backup config files
cp ~/.openviking/ov.conf ${BACKUP_DIR}/ 2>/dev/null || true
cp ~/.openviking/ovcli.conf ${BACKUP_DIR}/ 2>/dev/null || true

# Backup workspace (if exists)
WORKSPACE=$(python3 -c '
import json
import os
config_path = os.path.expanduser("~/.openviking/ov.conf")
if os.path.exists(config_path):
    with open(config_path) as f:
        cfg = json.load(f)
        ws = cfg.get("storage", {}).get("workspace", "./data")
        print(os.path.expanduser(ws))
' 2>/dev/null || echo "~/.openviking/data")

if [ -d "${WORKSPACE}" ]; then
    echo "Backing up workspace: ${WORKSPACE}"
    tar -czf ${BACKUP_DIR}/workspace_backup.tar.gz -C $(dirname ${WORKSPACE}) $(basename ${WORKSPACE})
fi

# Backup log
if [ -d ~/.openviking/log ]; then
    cp -r ~/.openviking/log ${BACKUP_DIR}/ 2>/dev/null || true
fi

echo "✓ Backup created at: ${BACKUP_DIR}"
ls -lh ${BACKUP_DIR}/

# ==========================================
# STEP 3: CONFIRM DELETION
# ==========================================
echo ""
echo "=========================================="
echo "WARNING: ABOUT TO DELETE ALL DATA!"
echo "=========================================="
echo "Workspace to delete: ${WORKSPACE}"
echo "Backup location: ${BACKUP_DIR}"
echo ""
read -p "Type 'DELETE' to confirm data removal: " CONFIRM

if [ "${CONFIRM}" != "DELETE" ]; then
    echo "Cleanup cancelled. Backup preserved at ${BACKUP_DIR}"
    exit 0
fi

# ==========================================
# STEP 4: DELETE DATA
# ==========================================
echo ""
echo "Step 4: Deleting data..."

# Delete workspace
if [ -d "${WORKSPACE}" ]; then
    echo "Deleting workspace: ${WORKSPACE}"
    rm -rf "${WORKSPACE}"
fi

# Optional: Delete old log (uncomment if needed)
# echo "Deleting old log..."
# rm -rf ~/.openviking/log/*

# Cleanup any temporary files
rm -f ~/.openviking/server.pid

echo "✓ Data deleted successfully"

# ==========================================
# STEP 5: COMPLETION
# ==========================================
echo ""
echo "=========================================="
echo "Cleanup Complete!"
echo "=========================================="
echo "Backup preserved at: ${BACKUP_DIR}"
echo ""
echo "Next steps:"
echo "1. Reconfigure ov.conf if needed"
echo "2. Start the server: openviking-server"
echo "3. Verify with: curl http://localhost:1933/health"
echo ""
echo "To restore from backup:"
echo "  tar -xzf ${BACKUP_DIR}/workspace_backup.tar.gz -C $(dirname ${WORKSPACE})"
簡易クリーンアップ（開発時のみ）
# WARNING: Only use in development!
# No backup created - data loss guaranteed!

# 1. Stop server
pkill -f openviking-server
sleep 2
pkill -9 -f openviking-server 2>/dev/null || true

# 2. Delete workspace (adjust path as needed)
rm -rf ~/.openviking/data

# 3. Cleanup PID and temp files
rm -f ~/.openviking/server.pid

echo "Quick cleanup complete"

検証とトラブルシューティング

ヘルスチェックの検証
# Basic health check (always available)
curl http://localhost:1933/health
# Expected: {"status": "ok"}

# Readiness check (verifies all components)
curl http://localhost:1933/ready
# Expected: {"status": "ready", "checks": {"agfs": "ok", "vectordb": "ok", "api_key_manager": "ok"}}

# System status via CLI (~/.openviking/ovcli.conf should be configured)
ov status
よくある問題と解決策
問題：サーバーが起動しない

確認事項：

# 1. Check if port is in use
lsof -i :1933
netstat -tulpn | grep 1933

# 2. Check log for errors
tail -10 ~/.openviking/log/openviking-server.log
tail -100 ~/.openviking/log/openviking.log


# 3. Verify config file is valid JSON
python3 -c 'import json, os; json.load(open(os.path.expanduser("~/.openviking/ov.conf"))); print("Config is valid")'

# 4. Verify virtual environment
source ~/.openviking/ov-venv/bin/activate
which openviking-server
pip list | grep openviking

解決策：

# If port conflict: kill the process or use different port
lsof -ti :1933 | xargs kill -9 2>/dev/null || true

# Or start on different port
nohup openviking-server --port 1934 > ~/.openviking/log/openviking-server.log 2>&1 &
問題：API キーのエラー

確認事項：

# Verify API keys in config
python3 -c '
import json, os
cfg = json.load(open(os.path.expanduser("~/.openviking/ov.conf")))
print("Embedding provider:", cfg.get("embedding", {}).get("dense", {}).get("provider"))
print("VLM provider:", cfg.get("vlm", {}).get("provider"))
print("API keys set:", bool(cfg.get("embedding", {}).get("dense", {}).get("api_key")), bool(cfg.get("vlm", {}).get("api_key")))
'

解決策： API キーが正しく、必要な権限を持っていることを確認します。モデルプロバイダーのエンドポイントへのネットワーク接続を確認します。API キーの有効期限が切れていないことを確認します。

前提条件

  • Python 3.10+ がインストールされていること
  • uv パッケージマネージャーが利用可能であること
  • ワークスペースとログに十分なディスク領域があること
  • 埋め込みモデルと VLM モデル用の API キーが設定されていること
  • モデルプロバイダーへのネットワークアクセスがあること（クラウドモデルを使用する場合）

コメント

Markdown 対応