ov-server-operate

仓库: volcengine/openviking
安装量: 37
排名: #19128

安装

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

OpenViking Server Operations This guide provides standard operating procedures for deploying, managing, and maintaining OpenViking servers in production environments. Table of Content Service Configuration Environment Setup with uv Server Startup with nohup Server Shutdown Data Cleanup Procedure Verification and Troubleshooting Service Configuration Default Paths and Structure OpenViking uses the following standard directory structure under ~/.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) ├── ... └── ... Configuration Files 1. Server Config ( ~/.openviking/ov.conf ) Create the configuration file with at minimum the following configuration. Note 1: Replace the api-key with your own api-key. If you don't have one, ask the user to get one (follow the Volcengine Ark platform guide). Note 2: Replace the root_api_key with your own root-api-key. Ask the user to set one — it will be used for authentication when the CLI connects to the server. { "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" ] } } , "embedding" : { "dense" : { "model" : "doubao-embedding-vision-250615" , "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 Config ( ~/.openviking/ovcli.conf ) For client connections from localhost: { "url" : "http://localhost:1933" , "api_key" : "your-root-api-key" } For remote connections, set the url to the remote server address (for example, the server EIP). Environment Setup with uv Step 1: Install uv (if not already installed)

macOS/Linux

curl -LsSf https://astral.sh/uv/install.sh | sh

Verify installation

uv --version Step 2: Create Virtual Environment Create a dedicated virtual environment at ~/.openviking/ov-venv :

Create venv with Python 3.10+

cd ~/.openviking uv venv --python 3.12 ov-venv Step 3: Activate and Install 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 Step 4: Create Log Directory mkdir -p ~/.openviking/log Server Startup with nohup Standard Startup Procedure

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 Verify Server is Running

Method 1: Check health endpoint

curl http://localhost:1933/health

Expected:

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 Server Shutdown Graceful Shutdown Procedure

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 Data Cleanup Procedure When to Use This Procedure Perform full data cleanup in these scenarios: Version upgrade with incompatible data format Corrupted or inconsistent data Need to reset to fresh state Storage space reclamation Standard Cleanup Workflow CRITICAL: ALWAYS BACKUP BEFORE DELETING DATA

==========================================

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 } ) " Quick Cleanup (for Development Only)

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" Verification and Troubleshooting Health Check Verification

Basic health check (always available)

curl http://localhost:1933/health

Expected:

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 Common Issues and Solutions Issue: Server won't start Check:

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 Solution:

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 & Issue: API Key Errors Check:

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"))) ' Solution: Verify API keys are correct and have the required permissions. Check network connectivity to the model provider endpoints. Ensure API keys are not expired. Prerequisites Python 3.10+ installed uv package manager available Sufficient disk space for workspace and log API keys for embedding and VLM models configured Network access to model providers (if using cloud models)

← 返回排行榜