运维与排障
日常检查、升级备份、常见故障与紧急处置的运行手册。
01日常检查
核心状态airlock ... status核心、监听器与脱敏路由摘要。
路由健康airlock ... routes health <alias>不发送应用请求正文；SSH 只验证 Host Key 与认证。
安装器契约airlock-installer doctor校验当前平台发布产物完整性。
升级流程
- 停止服务（桌面端：退出 airlockd；服务器：
systemctl stop airlock）。 - 离线备份
/var/lib/airlock、control/web token 文件。 - 替换二进制或更新 npm 包并重新安装。
- 启动后执行
status 与关键路由 routes health。
备份即 Secret数据目录包含上游描述与加密后的凭据，备份文件必须按 Secret 保管。
常见故障
Host Key 不匹配routes health → host key mismatch停用路由，重新 probe 并在独立渠道核对新指纹，绝不绕过该错误。
上游不可达upstream unavailable检查 DNS、端口与 Direct/Proxy/Auto 策略；Auto 不会重放已开始的请求。
本地 SSH 被拒SSH authentication failed确认路由已启用、本地用户名唯一、本地密码/公钥正确。
LLM 被限流429 capacity_limit / rate limit检查 RPM/并发配置与全局网关容量。
端口被占用bind: address in use在桌面端查看占用者并确认结束，或切换非特权端口。
紧急处置
立即全停airlock --data-dir /var/lib/airlock --token-file /etc/airlock/control.token \
routes stop-all --yes
全停保留全部配置；处置完成后逐条审查并重新启用。桌面端同样提供"停止全部"按钮。
监控建议
- 对关键路由配置外部健康探测（HTTP 层或 SSH 隧道），失败时告警。
- 定期轮换本地凭据与上游密码；人员变动时立即轮换。
- 关注活动页的
blocked 记录：持续失败可能表示凭据泄露或误配置。 - 订阅项目 Release，按升级流程更新。
Operations and troubleshooting
A runbook for daily checks, upgrades, backups, common failures, and emergency response.
01Daily checks
Core statusairlock ... statusCore, listeners, and sanitized route summaries.
Route healthairlock ... routes health <alias>No application body; SSH validates host key and authentication only.
Installer contractairlock-installer doctorVerifies the current platform release artifact.
Upgrade procedure
- Stop the service (desktop: quit airlockd; server:
systemctl stop airlock). - Back up
/var/lib/airlock and both token files offline. - Replace binaries or update the npm package and reinstall.
- Run
status and routes health for critical routes.
Backups are secretsThe data directory contains upstream descriptors and protected credentials; store backups accordingly.
Common failures
Host-key mismatchroutes health → host key mismatchDisable the route, re-probe, and confirm the new fingerprint over an independent channel. Never bypass this error.
Upstream unreachableupstream unavailableCheck DNS, port, and Direct/Proxy/Auto policy. Auto never replays an already-started request.
Local SSH deniedSSH authentication failedConfirm the route is enabled, the local username is unique, and the local password/public key is correct.
LLM throttled429 capacity_limit / rate limitReview RPM/concurrency and global gateway capacity.
Port in usebind: address in useInspect the owner in the desktop settings and confirm termination, or switch ports.
Emergency response
Stop everything nowairlock --data-dir /var/lib/airlock --token-file /etc/airlock/control.token \
routes stop-all --yes
Stop-all retains all configuration; review and re-enable per route afterward. The desktop also has a Stop all button.
Monitoring recommendations
- Probe critical routes externally and alert on failure.
- Rotate local and upstream credentials regularly and after personnel changes.
- Watch
blocked activity: persistent failures may mean leaked credentials or misconfiguration. - Subscribe to releases and follow the upgrade procedure.
運用とトラブルシューティング
日常チェック、アップグレード、バックアップ、よくある障害、緊急対応のランブックです。
01日常チェック
コア状態airlock ... statusコア、リスナー、サニタイズ済みルート要約。
ルートヘルスairlock ... routes health <alias>アプリケーション本文を送信せず、SSH は Host Key と認証のみ検証。
インストーラー契約airlock-installer doctor現在のプラットフォームのアーティファクトを検証。
アップグレード手順
- サービス停止（デスクトップ：airlockd 終了、サーバー：
systemctl stop airlock）。 /var/lib/airlock と 2 つのトークンファイルをオフラインでバックアップ。- バイナリ差し替え、または npm パッケージ更新と再インストール。
- 起動後、
status と重要ルートの routes health を実行。
バックアップは Secretデータディレクトリには上流の記述と保護された認証情報が含まれます。
よくある障害
Host Key 不一致routes health → host key mismatchルートを無効化し、再プローブして独立経路でフィンガープリントを確認。エラーを無視しない。
上流に到達できないupstream unavailableDNS・ポート・Direct/Proxy/Auto を確認して再試行。Auto は開始済みリクエストを再送しない。
ローカル SSH 拒否SSH authentication failedルート有効化、ローカルユーザー名の一意性、ローカルパスワード/公開鍵を確認。
LLM レート制限429 capacity_limit / rate limitRPM・並列上限とゲートウェイ容量を確認。
ポート使用中bind: address in use設定画面で占有プロセスを確認し、正常終了を承認するかポートを変更。
緊急対応
即時全停止airlock --data-dir /var/lib/airlock --token-file /etc/airlock/control.token \
routes stop-all --yes
全停止は設定を保持します。対応後、ルートごとに確認して再開してください。
モニタリングの推奨
- 重要ルートに外部ヘルスプローブを設定し、失敗時にアラート。
- 認証情報を定期的にローテーションし、要員変更時は即時。
- Activity の
blocked 記録を監視（認証情報漏えいや設定ミスの兆候）。 - Release を購読し、アップグレード手順に従って更新。
