常见问题 Q&A
按类别整理的详细问答。找不到答案时，可先使用页面顶部搜索，或查看对应章节。
安装安装与平台
支持哪些平台？如何安装？
macOS 12+（Apple Silicon 与 Intel）、Windows 10+（x64/x86/arm64）、Linux x64/arm64，以及 64 位树莓派。统一命令：npm install -g airlock-relay && airlock-installer install --open。
npm 安装和直接下载安装包有什么区别？
没有功能差异。npm 方式由安装器下载并校验固定校验和产物后安装；直接下载需要你手动执行 shasum -a 256 -c SHA256SUMS-v0.1.8.txt 核对。
为什么 Windows/Linux 安装包未签名？
预览阶段尚未配置 Authenticode 证书与 Apple Developer ID。因此 SmartScreen/Gatekeeper 会提示；请以官方 Release 的 SHA-256 清单为准。
树莓派 32 位（armv7）如何安装？
GitHub 没有 armv7 构建机，需要在树莓派本机克隆仓库并运行 bash scripts/build-armv7-desktop.sh，产物可上传到 Release 后纳入安装契约。
如何升级到新版本？
npm install -g airlock-relay@latest 后重新执行 airlock-installer install；Server Core 请先备份再替换二进制。
安全与边界
Airlock 是代理或 VPN 吗？
不是。它是固定路由转发器：每条路由绑定一个预先配置的上游，调用方无法指定任意目标，也不能获得通用网络出口。
调用方能看到上游凭据吗？
不能。上游 URL、账号、密码、私钥与 API Key 只存在于本机 SecretStore，只在策略校验通过后于上游请求时注入。
本机管理员能绕过 Airlock 吗？
能。本机管理员、root 或能调试进程的攻击者不在威胁模型内；Airlock 是凭据隔离层，不是沙箱。
Secret 存放在哪里？
默认是本机 0600 文件；macOS 可选 Keychain、Windows Credential Manager、Linux Secret Service。路由摘要与活动记录不包含 Secret。
日志和统计会泄露提示词或命令吗？
默认不会。活动记录脱敏；SSH 命令审计需显式开启并保存在本机 0600 滚动文件；LLM 统计只保留数字。
使用与路由
如何创建第一条路由？
桌面端：路由 → 新增路由 → 选择类型并填写；Server Core：编写 0600 JSON 规格 → routes create → routes health → routes enable。详细步骤见从零开始。
一条本地用户名可以被多个路由使用吗？
不可以。SSH 本地用户名在本机唯一；不同路由应使用不同本地用户名，上游地址可以共享。
如何开启 SSH 交互式 Shell？
在路由设置中开启"允许交互式 Shell"，它要求同时开启"所有命令"（高风险确认）。开启后 PuTTY/ssh 直接进入上游 Shell，PTY 元数据仅在开启时转发。
LLM 路由的 Token 统计会保存提示词吗？
不会。统计默认关闭；开启后只记录调用次数与上游返回的 token 数，进程重启后清零。
本地凭据泄露了怎么办？
立即轮换：桌面端"编辑路由 → 轮换"，或 CLI routes rotate-credential <alias>。旧凭据立即失效；必要时先用 routes disable 停用。
运维与故障
Host Key 不匹配怎么办？
停用路由，重新 ssh probe，并通过独立渠道核对新指纹后更新规格。绝不绕过该错误。
端口被占用怎么办？
桌面设置页查看占用者（仅当前用户），确认后优雅结束；或切换到其他非特权端口。Airlock 不会强制终止他人进程。
上游不可达怎么办？
检查 DNS、端口与 Direct/Proxy/Auto 出口策略，然后 routes health 重试。Auto 不会重放已开始的请求。
如何紧急全停？
routes stop-all --yes（或桌面端"停止全部"）。配置保留，处置后逐条审查再启用。
如何备份与恢复？
停止服务后离线复制 /var/lib/airlock 与 control/web token 文件；恢复时原样放回并启动。备份按 Secret 保管。
发布与签名
为什么要同时校验 SHA-256 和 GPG？
SHA-256 保证文件与官方发布一致；GPG 签名（Linux）额外提供发布者身份校验。安装器会在安装前强制校验 SHA-256。
为什么还没有 Apple 公证和 Windows 签名？
需要 Developer ID 证书与 Authenticode 证书（含身份审核与费用）。当前为技术预览，采用固定校验和 + 发布边界来降低风险。
审计状态如何？
v0.1.4 起完成维护者执行的生产就绪安全审计；尚未进行独立第三方渗透测试。完整记录见审计文档。
如何报告安全问题？
阅读 SECURITY.md，通过其中给出的私密渠道报告，不要在公开 issue 中贴出细节。
Frequently asked questions
Detailed Q&A by category. Use the search box at the top if you cannot find an answer quickly.
InstallInstallation and platforms
Which platforms are supported and how do I install?
macOS 12+ (Apple Silicon and Intel), Windows 10+ (x64/x86/arm64), Linux x64/arm64, and 64-bit Raspberry Pi. One command: npm install -g airlock-relay && airlock-installer install --open.
What is the difference between npm and direct download?
No functional difference. The npm installer downloads and verifies the pinned artifact; manual downloads require you to run shasum -a 256 -c SHA256SUMS-v0.1.8.txt yourself.
Why are the Windows/Linux installers unsigned?
The preview stage has no Authenticode or Developer ID certificates yet, so SmartScreen/Gatekeeper warn. Trust the official SHA-256 manifest.
How do I install on a 32-bit Raspberry Pi (armv7)?
There is no hosted armv7 runner. Clone the repository on the Pi and run bash scripts/build-armv7-desktop.sh; the artifacts can be uploaded to the release and added to the installer contract.
How do I upgrade?
Run npm install -g airlock-relay@latest, then airlock-installer install again. For Server Core, back up before replacing binaries.
Security and boundary
Is Airlock a proxy or VPN?
No. It is a fixed-route relay: each route binds one preconfigured upstream, and callers can neither choose arbitrary targets nor gain a general network egress.
Can callers see upstream credentials?
No. Upstream URLs, accounts, passwords, private keys, and API keys live only in the local SecretStore and are injected only after policy approval.
Can a local administrator bypass Airlock?
Yes. Admins, root, or process-debugging attackers are outside the threat model. Airlock is a credential-isolation layer, not a sandbox.
Where are secrets stored?
A local 0600 file by default; optionally Keychain, Credential Manager, or Secret Service. Route summaries and activity never include secrets.
Do logs or statistics leak prompts or commands?
No by default. Activity is sanitized; SSH command audit is explicit and stored in a local 0600 rolling file; LLM statistics keep numbers only.
Usage and routes
How do I create my first route?
Desktop: Routes → New route. Server Core: write a 0600 JSON spec → routes create → routes health → routes enable. See Getting started.
Can one local username be reused?
No. SSH local usernames are unique on the machine; upstream addresses may be shared.
How do I enable the interactive SSH shell?
Enable "Allow interactive shell" in the route, which requires "All commands" (high-risk confirmation). PuTTY/ssh then enter the upstream shell and PTY metadata is forwarded.
Does LLM token tracking save prompts?
No. Tracking is off by default; when enabled it keeps call counts and upstream token numbers only, resetting on restart.
What if a local credential leaks?
Rotate immediately: desktop "Edit route → Rotate" or routes rotate-credential <alias>. Old credentials stop working instantly; disable the route first if needed.
Operations and failures
What if the host key mismatches?
Disable the route, re-run ssh probe, confirm the new fingerprint over an independent channel, then update the spec. Never bypass this error.
What if a port is in use?
Inspect the owner in desktop settings (current-user processes only), confirm a graceful termination, or switch to another unprivileged port.
What if the upstream is unreachable?
Check DNS, port, and Direct/Proxy/Auto policy, then retry routes health. Auto never replays an already-started request.
How do I stop everything now?
routes stop-all --yes (or the desktop Stop all button). Configuration is retained; review and re-enable per route afterward.
How do I back up and restore?
Stop the service and copy /var/lib/airlock plus both token files offline. Restore by placing them back and starting. Treat backups as secrets.
Release and signing
Why verify both SHA-256 and GPG?
SHA-256 proves the file matches the official release; the GPG signature (Linux) additionally authenticates the publisher. The installer enforces SHA-256 before installing.
Why is there no Apple notarization or Windows signing yet?
They require Developer ID and Authenticode certificates (identity review and cost). This is a technical preview using pinned checksums and explicit release boundaries.
What is the audit status?
The maintainer-run production-readiness audit is complete since v0.1.4; no independent third-party penetration test yet. See the audit document.
How do I report a security issue?
Read SECURITY.md and use the private channel listed there; do not post details in public issues.
よくある質問 Q&A
カテゴリ別の詳細なQ&Aです。上部の検索ボックスもご利用ください。
インストールインストールとプラットフォーム
対応プラットフォームとインストール方法は？
macOS 12+（Apple Silicon / Intel）、Windows 10+（x64/x86/arm64）、Linux x64/arm64、64bit Raspberry Pi。共通コマンド：npm install -g airlock-relay && airlock-installer install --open。
npm と直接ダウンロードの違いは？
機能差はありません。npm は固定 checksum を検証してから導入します。手動では shasum -a 256 -c SHA256SUMS-v0.1.8.txt を実行してください。
Windows/Linux が未署名なのはなぜ？
プレビュー段階のため Authenticode 証明書と Developer ID が未設定です。SmartScreen/Gatekeeper の警告が出ますが、公式 SHA-256 マニフェストで確認してください。
32bit Raspberry Pi（armv7）の導入は？
ホスト型 armv7 ランナーがないため、Pi 上でリポジトリを clone し bash scripts/build-armv7-desktop.sh を実行します。生成物は Release にアップロードできます。
アップグレード方法は？
npm install -g airlock-relay@latest の後に airlock-installer install を再実行します。Server Core は先にバックアップしてください。
セキュリティと境界
Airlock はプロキシや VPN ですか？
違います。固定ルートリレーであり、各ルートは事前設定された上流にバインドされます。呼び出し元が任意の宛先を指定することはできません。
呼び出し元は上流の認証情報を見られますか？
いいえ。上流 URL・アカウント・パスワード・秘密鍵・API Key はローカルの SecretStore にのみ存在し、ポリシー承認後に注入されます。
ローカル管理者は回避できますか？
できます。管理者・root・プロセスをデバッグできる攻撃者は脅威モデルの外です。Airlock はサンドボックスではなく認証情報の分離層です。
Secret はどこに保存されますか？
既定はローカル 0600 ファイル。オプションで Keychain / Credential Manager / Secret Service も利用できます。要約やアクティビティに Secret は含まれません。
ログや統計はプロンプトやコマンドを漏らしますか？
既定では漏らしません。アクティビティはサニタイズされ、SSH コマンド監査は明示的に有効化した場合のみローカル 0600 ファイルに保存されます。
利用とルート
最初のルートはどう作りますか？
デスクトップ：Routes → New route。Server Core：0600 JSON 仕様を書き、routes create → routes health → routes enable。はじめにを参照してください。
ローカルユーザー名は再利用できますか？
できません。SSH ローカルユーザー名はマシン内で一意です。上流アドレスは共有できます。
対話型 SSH シェルはどう有効化しますか？
ルート設定で「対話型シェルを許可」を有効にします（「すべてのコマンド」が必要・高リスク確認）。有効時は PuTTY/ssh が上流シェルへ入り、PTY メタデータも転送されます。
LLM の利用統計はプロンプトを保存しますか？
保存しません。既定で無効で、有効時も呼び出し回数とトークン数のみを保持し、再起動でリセットされます。
ローカル認証情報が漏れたら？
すぐにローテーションします：デスクトップの「ローテーション」または routes rotate-credential <alias>。必要なら先に routes disable で停止してください。
運用と障害
Host Key 不一致の対処は？
ルートを無効化し、ssh probe を再実行して独立した経路でフィンガープリントを確認してから仕様を更新します。エラーを無視しないでください。
ポートが使用中の場合？
デスクトップ設定で占有プロセス（自分のユーザーのみ）を確認し、正常終了を承認するか別のポートに切り替えます。
上流に到達できない場合？
DNS・ポート・Direct/Proxy/Auto ポリシーを確認し、routes health を再実行します。Auto は開始済みリクエストを再送しません。
緊急停止は？
routes stop-all --yes（またはデスクトップの「すべて停止」）。設定は保持され、確認後にルートごとに再開できます。
バックアップと復元は？
サービス停止後に /var/lib/airlock と 2 つのトークンファイルをオフラインでコピーします。復元は元の場所に戻して起動します。バックアップも Secret として扱います。
リリースと署名
SHA-256 と GPG の両方を検証する理由は？
SHA-256 は公式リリースとの一致を保証し、GPG 署名（Linux）は発行者を認証します。インストーラーは導入前に SHA-256 を強制検証します。
Apple 公証や Windows 署名がない理由は？
Developer ID 証明書と Authenticode 証明書（本人確認と費用）が必要です。現状は技術プレビューとして、固定 checksum と明確なリリース境界で運用しています。
監査状況は？
v0.1.4 以降、保守者による本番準備監査が完了しています。独立した第三者ペネトレーションテストは未実施です。監査ドキュメントを参照してください。
セキュリティ問題の報告方法は？
SECURITY.md に記載された非公開チャネルで報告してください。公開 issue に詳細を書かないでください。
