xianwen-server-ops

name	xianwen-server-ops
description	Server operations for Xianwen Online: Hetzner VPS management, server stability, connection pool tuning, WebSocket management, security hardening, monitoring, and performance optimization. Use when dealing with server issues, '伺服器', '斷線', '穩定性', or infrastructure.

Xianwen Server Operations

Server infrastructure management, extracted from major migration and stability sessions.

Infrastructure

Component	Provider	Details
Game Server	Hetzner VPS (Tokyo)	Docker Compose, Rust/Actix-Web
Database	Neon PostgreSQL	ap-southeast-1, pooler connection
DNS	Cloudflare	play.xianwen.online
Previous hosting	Fly.io	Migrated away for stability

Server Architecture

Hetzner VPS (5.223.42.8)
├── Docker Compose
│   ├── xianwen-server (Rust binary)
│   └── Redis (session cache)
├── Nginx (reverse proxy, SSL)
└── Monitoring scripts

Connection Management

Key Settings

// Database pool
max_connections: 16  // Increased from 8 after load issues
min_connections: 2

// WebSocket
// DashMap replaces RwLock<HashMap> for connection tracking
// ConnectionManager is now decentralized

Common Stability Issues

Symptom	Root Cause	Fix
Players disconnected randomly	Connection pool exhaustion	Increase pool size, add timeout
Buttons not responding	WebSocket dead but not detected	Add heartbeat/ping mechanism
Server crash under load	RwLock contention in game.rs	Use DashMap, split by domain
Login fails intermittently	Redis connection not reused	Use ConnectionManager singleton
Cannot interact after reconnect	State not restored on WS reconnect	Re-send character state on connect

Server Domain Split

game.rs was split into domain-specific handlers:

• combat.rs — Battle logic
• movement.rs — Location/map transitions
• chat.rs — Player communication
• This prevents lock contention across unrelated features

Security Hardening

VPS Security

• SSH key-only authentication (no password)
• UFW firewall (allow 22, 80, 443, game port)
• Fail2ban for brute force protection
• Regular security updates

Application Security

• CORS configured for play.xianwen.online
• Rate limiting on API endpoints
• Input sanitization for player text input
• Discord OAuth token validation

Deployment on Hetzner

# SSH to server
ssh root@5.223.42.8

# Pull and rebuild
cd /opt/xianwen-online
git pull origin main
docker compose build --no-cache
docker compose up -d

# Check logs
docker compose logs -f --tail=100 xianwen-server

# Check health
curl localhost:8080/health

Monitoring

Key Metrics to Watch

• DB pool utilization (connections in use / max)
• WebSocket channel depth (message queue size)
• Lock wait time (should be near 0 with DashMap)
• Memory usage (Rust binary + Redis)
• Response latency (p50, p95, p99)

Log Analysis

# Check for panics
docker compose logs xianwen-server | grep -i "panic\|error\|warn"

# Check connection issues
docker compose logs xianwen-server | grep -i "connection\|pool\|timeout"

Migration from Fly.io

This migration was completed. Key changes:

1. Moved from Fly.io → Hetzner VPS (Tokyo region)
2. Database: Fly Postgres → Neon PostgreSQL
3. DNS updated in Cloudflare
4. Discord OAuth redirect URIs updated
5. GitHub Actions deploy target updated