安裝與升級疑難排解 Install & upgrade troubleshooting インストールとアップグレードのトラブルシューティング

1. 先跑內建的健檢：它會直接告訴你哪裡壞了、該下哪一行指令 1. Run the built-in health check first: it names what is broken and the exact command to fix it 1. まず内蔵の健全性チェックを実行する：どこが壊れているかと、直すためのコマンドをそのまま教えてくれます

sudo bash /opt/jt-ipam/scripts/jt-ipam.sh doctor

它會逐項檢查設定檔、資料庫、遷移版本、前端 dist、systemd 服務與計時器、監聽埠、nginx、備份目錄與 ICMP 權限，並對每個紅字附上修復指令。大部分安裝問題在這一步就結束了。 It checks the env file, database, migration revision, frontend dist, systemd units and timers, the listening port, nginx, the backup directory and ICMP capability, and prints a fix command next to anything red. Most install problems end here. 設定ファイル、データベース、マイグレーションのリビジョン、フロントエンドの dist、systemd のユニットとタイマー、待ち受けポート、nginx、バックアップ用ディレクトリ、ICMP の権限を順に確認し、赤く出た項目には必ず修正コマンドを添えます。インストールの問題はたいていここで片付きます。

2. 重跑一次是安全的 2. Re-running is safe 2. 再実行しても安全です

install 與 upgrade 都可重複執行：已完成的步驟會跳過，不會把資料庫或設定洗掉。修掉錯誤原因後直接重跑同一行指令即可。 Both install and upgrade are idempotent: completed steps are skipped and neither wipes your database or configuration. Fix the cause, then re-run the exact same command. install も upgrade も何度実行しても構いません。完了済みの手順は飛ばされ、データベースや設定が消えることはありません。原因を直したら、まったく同じコマンドをもう一度実行してください。

3. 看真正的錯誤訊息，不要只看最後一行 3. Read the real error, not just the last line 3. 最後の一行だけでなく、本当のエラーを読む

sudo journalctl -u jt-ipam-backend -n 80 --no-pager
sudo systemctl status jt-ipam-backend --no-pager

腳本印出的 FATAL: 通常只是結果；真正的原因（缺套件、密碼錯、埠被占用）幾乎都在上面幾行或 journal 裡。 The FATAL: line the script prints is usually the symptom. The cause (a missing package, a bad password, a port already in use) is a few lines above it or in the journal. スクリプトが出す FATAL: はたいてい結果にすぎません。本当の原因（パッケージ不足、パスワード誤り、ポートの使用中）は、その数行上か journal の中にあります。

升級每次都停在 git，而且重跑幾次都一樣 Every upgrade stops at git, and re-running changes nothing アップグレードが毎回 git で止まり、何度やり直しても同じ

本機的原始碼歷程已經無法快轉到遠端（有人在機器上改過並提交、淺層 clone、或上游歷程被改寫）。因為升級用的是 git pull --ff-only，而且腳本開了 set -e，它會停在第一步：備份、遷移、建置、重啟全都沒跑，所以每次重跑都停在同一個地方。 The local source history can no longer fast-forward onto the remote (someone committed an edit on the box, a shallow clone, or upstream history was rewritten). The upgrade pulls with git pull --ff-only under set -e, so it stops at step one (no backup, no migration, no build, no restart), and every re-run stops in exactly the same place. ローカルのソース履歴がリモートへ早送り（fast-forward）できなくなっています。原因は、このマシン上で誰かが編集をコミットした、浅いクローンだった、上流の履歴が書き換えられた、のいずれかです。アップグレードは set -e の下で git pull --ff-only を実行するため、最初の手順で止まります。バックアップもマイグレーションもビルドも再起動も行われません。リポジトリの状態が変わらない以上、何度やり直しても同じ場所で止まります。

v0.6.13 起已自動處理：升級偵測到無法快轉時，會把只存在於本機的提交保留到 upgrade-recovery/<時間戳> 分支，再重設到遠端並繼續升級。先升到 0.6.13 以上就不會再遇到。 Fixed automatically since v0.6.13: the upgrade keeps any local-only commits on an upgrade-recovery/<timestamp> branch, resets to the remote and carries on. Once you are past 0.6.13 this cannot recur. v0.6.13 以降は自動で復旧します：早送りできないと分かると、このマシンにしかないコミットを upgrade-recovery/<タイムスタンプ> ブランチに退避し、リモートへリセットしてアップグレードを続行します。0.6.13 以降に上げてしまえば、この問題は再発しません。

停在舊版本的話，手動做同一件事： If you are stuck on an older version, do the same thing by hand: 古いバージョンで止まっている場合は、同じことを手作業で行います。

cd /opt/jt-ipam
sudo -u jtipam git fetch origin
# 只在本機的提交先留成分支（沒有就跳過這行） / keep local-only commits / ローカル限定のコミットを退避
sudo -u jtipam git branch pre-upgrade-$(date +%Y%m%d) HEAD
sudo -u jtipam git reset --hard origin/main
sudo bash scripts/jt-ipam.sh upgrade

reset --hard 不會動到你的設定與資料：設定在 /etc/jt-ipam/、資料在 PostgreSQL、上傳檔在 /var/lib/jt-ipam/，原始碼樹本來就只是上游的副本。 reset --hard does not touch your configuration or data: config lives in /etc/jt-ipam/, data in PostgreSQL, uploads in /var/lib/jt-ipam/. The source tree is only ever a copy of upstream. reset --hard は設定やデータには触れません。設定は /etc/jt-ipam/、データは PostgreSQL、アップロードしたファイルは /var/lib/jt-ipam/ にあります。ソースツリーはあくまで上流の複製にすぎません。

Upgrade would overwrite local changes Upgrade would overwrite local changes Upgrade would overwrite local changes（ローカルの変更を上書きしてしまう）

原始碼樹裡有被改過的追蹤檔案（常見於手動修補過 scripts/jt-ipam.sh，或上次升級只完成一半）。確定那些改動不需要保留就： Tracked files in the source tree have been modified: usually a hand-patched scripts/jt-ipam.sh, or a half-finished previous upgrade. If you do not need those edits: ソースツリー内の管理対象ファイルが変更されています。多くは scripts/jt-ipam.sh を手で修正した場合か、前回のアップグレードが途中で終わった場合です。その変更が不要なら次を実行します。

sudo bash /opt/jt-ipam/scripts/jt-ipam.sh upgrade --force

想先看改了什麼：sudo -u jtipam git -C /opt/jt-ipam diff；想留著就 git stash。 To see what changed first: sudo -u jtipam git -C /opt/jt-ipam diff; to keep it, git stash. 変更内容を先に確認するなら sudo -u jtipam git -C /opt/jt-ipam diff、残しておきたいなら git stash を使います。

Cannot reach origin/main（連不到 GitHub） Cannot reach origin/main (no route to GitHub) Cannot reach origin/main（GitHub に到達できない）

先確認這台機器連得出去，再確認 proxy 設定： Check outbound access first, then the proxy settings: まず外部へ出られるかを確認し、次にプロキシ設定を確認します。

sudo -u jtipam git -C /opt/jt-ipam ls-remote origin
# proxy が要る場合（git は apt のプロキシ設定を引き継ぎません）
sudo -u jtipam git config --global http.proxy http://proxy.example.com:3128

離線環境：把新版原始碼自行複製到 /opt/jt-ipam，再用 upgrade --no-pull 跑後面的備份/遷移/建置/重啟。 Air-gapped: copy the new source into /opt/jt-ipam yourself, then run upgrade --no-pull to do the backup / migration / build / restart steps. 閉域環境では、新しいソースを自分で /opt/jt-ipam に配置したうえで upgrade --no-pull を実行し、バックアップ/マイグレーション/ビルド/再起動だけを行わせます。

停在 alembic upgrade head Stops at alembic upgrade head alembic upgrade head で止まる

資料庫遷移失敗。alembic 是單一交易，失敗會整段還原，資料庫仍是升級前的狀態。看完整錯誤： A migration failed. Alembic runs each revision in a transaction, so the database is still in its pre-upgrade state. Read the full error: マイグレーションが失敗しています。alembic は各リビジョンをトランザクションで実行するため、データベースはアップグレード前の状態のままです。完全なエラーを確認してください。

cd /opt/jt-ipam/backend
sudo -u jtipam bash -c 'set -a; source /etc/jt-ipam/backend.env; set +a; .venv/bin/alembic current'
sudo -u jtipam bash -c 'set -a; source /etc/jt-ipam/backend.env; set +a; .venv/bin/alembic upgrade head'

• extension "vector" is not available → 見下面 pgvector 那一則。 extension "vector" is not available → see the pgvector entry below. extension "vector" is not available → 下の pgvector の項目を参照してください。
• permission denied → backend.env 裡的資料庫帳號不是該資料庫的擁有者。 permission denied → the DB user in backend.env does not own the database. permission denied → backend.env のデータベースユーザーがそのデータベースの所有者になっていません。
• 重複鍵 / 約束衝突 → 多半是舊資料不乾淨，把完整訊息附在 issue 裡。 Duplicate key / constraint violations → usually pre-existing dirty data; paste the whole message into an issue. 重複キーや制約違反 → 多くは既存データの不整合です。メッセージ全文を添えて issue を立ててください。

升級在這一步之前已經做過資料庫備份，檔案在 /var/backups/jt-ipam/<日期>/。 The upgrade takes a database dump before this step; it is in /var/backups/jt-ipam/<date>/. この手順の前にデータベースのダンプが取られており、/var/backups/jt-ipam/<日付>/ に置かれています。

停在 Building frontend（前端建置失敗） Stops at "Building frontend" Building frontend で止まる（フロントエンドのビルド失敗）

三個常見原因：Node 版本太舊、pnpm 不在、記憶體不足。 Three usual causes: Node too old, pnpm missing, or not enough memory. よくある原因は三つです。Node が古い、pnpm が無い、メモリが足りない。

node -v          # >= 18 が必要（推奨は 20）
pnpm -v          # 無ければ: sudo npm install -g pnpm@9
free -m          # ビルドには 1 GB 程度の空きメモリが必要

記憶體吃緊的機器可以先開一個暫時的 swap 再重跑升級；或手動建置後再重跑 upgrade --no-pull： On a memory-tight box, add temporary swap and re-run; or build by hand and then re-run upgrade --no-pull: メモリが厳しいマシンでは、一時的な swap を追加してからやり直すか、手動でビルドしてから upgrade --no-pull を実行します。

cd /opt/jt-ipam/frontend && sudo -u jtipam pnpm install && sudo -u jtipam pnpm build

did not come up after restart（升級到最後服務起不來） "did not come up after restart" did not come up after restart（最後にサービスが起動しない）

sudo journalctl -u jt-ipam-backend -n 80 --no-pager

• ENCRYPTION_KEY: invalid format → 必須是 32 位元組的 base64（44 字元、結尾 =）。 ENCRYPTION_KEY: invalid format → it must be 32-byte base64 (44 chars, ending in =). ENCRYPTION_KEY: invalid format → 32 バイトを base64 にしたもの（44 文字、末尾は =）である必要があります。
• Address already in use → 埠被占用：sudo ss -ltnp | grep -E '8000|8443'。 Address already in use → check sudo ss -ltnp | grep -E '8000|8443'. Address already in use → ポートが使用中です。sudo ss -ltnp | grep -E '8000|8443' で確認します。
• password authentication failed → backend.env 的資料庫密碼與實際不符。 password authentication failed → the DB password in backend.env no longer matches. password authentication failed → backend.env のデータベースパスワードが実際と一致していません。
• 記憶體不足被 OOM 殺掉（小於 2 GB 的機器）→ 在 backend.env 設 ARGON2_MEMORY_COST_KIB=32768。 Killed by the OOM reaper (under 2 GB RAM) → set ARGON2_MEMORY_COST_KIB=32768 in backend.env. メモリ不足で OOM に落とされた（2 GB 未満のマシン）→ backend.env に ARGON2_MEMORY_COST_KIB=32768 を設定します。

怎麼還原到升級前的狀態 How to go back to the pre-upgrade state アップグレード前の状態に戻すには

升級中斷時腳本會印出這三步，這裡是完整版本： The script prints these three steps when an upgrade aborts; here they are in full: アップグレードが中断すると、スクリプトはこの三つの手順を表示します。以下はその完全版です。

# 1) ソースをアップグレード前のコミットへ戻す（開始時に表示されています）
sudo -u jtipam git -C /opt/jt-ipam reset --hard <old commit>

# 2) データベースを戻す（マイグレーションが完了した場合のみ必要）
sudo systemctl stop jt-ipam-backend
sudo -u postgres pg_restore --clean --no-owner -d jt_ipam \
     /var/backups/jt-ipam/<date>/jt-ipam-<date>.dump

# 3) フロントエンドを再ビルドして起動
cd /opt/jt-ipam/frontend && sudo -u jtipam pnpm install && sudo -u jtipam pnpm build
sudo systemctl start jt-ipam-backend

還原資料庫必須用同一把 ENCRYPTION_KEY，否則 DNS/API 等加密欄位解不開。 Restoring the database requires the same ENCRYPTION_KEY, or encrypted fields (DNS / API credentials) cannot be decrypted. データベースを戻すときは同じ ENCRYPTION_KEY が必要です。違うと DNS や API の資格情報など暗号化された項目を復号できません。

extension "vector" is not available，可是 pgvector 明明裝了 extension "vector" is not available, but pgvector is installed extension "vector" is not available と出るのに pgvector は入っている

這台機器多半本來就有一個 PostgreSQL 叢集（SonarQube、GitLab 之類帶來的）。jt-ipam 連的是 127.0.0.1:5432，也就是那個既有叢集，所以 pgvector 必須裝它的主版本；裝在別的版本上完全沒有作用。 This host almost certainly already runs a PostgreSQL cluster (from SonarQube, GitLab, …). jt-ipam connects to 127.0.0.1:5432 (that cluster), so pgvector has to be installed for its major version; installing it for another version does nothing. このホストにはほぼ確実に既存の PostgreSQL クラスタがあります（SonarQube や GitLab などが入れたもの）。jt-ipam は 127.0.0.1:5432、つまりその既存クラスタに接続するため、pgvector はそのクラスタのメジャーバージョン向けに入れる必要があります。別のバージョン向けに入れても効果はありません。

sudo -u postgres psql -tAc 'SHOW server_version_num'   # 例: 180004 → メジャー 18
sudo apt install -y postgresql-18-pgvector
sudo -u postgres psql -d jt_ipam -c 'CREATE EXTENSION IF NOT EXISTS vector;'
sudo bash /opt/jt-ipam/scripts/jt-ipam.sh install …     # 同じコマンドを再実行

v0.5.161 起安裝腳本會自己偵測執行中叢集的版本、裝對應的 pgvector，也不會再多裝一個 server 套件（那會生出第二個叢集）。 Since v0.5.161 the installer detects the running cluster's version, installs the matching pgvector, and no longer pulls a second server package (which would create a second cluster). v0.5.161 以降、インストーラは稼働中クラスタのバージョンを検出して対応する pgvector を入れます。サーバーパッケージを重ねて入れること（＝二つ目のクラスタができてしまう）もありません。

This host already runs PostgreSQL < 16 This host already runs PostgreSQL < 16 既存の PostgreSQL が 16 未満だと言われる

jt-ipam 需要 PostgreSQL 16 以上。既有叢集版本太舊時有兩條路：升級那個叢集，或讓 jt-ipam 連別的資料庫，在 /etc/jt-ipam/backend.env 改 POSTGRES_HOST / POSTGRES_PORT 後重跑安裝。 jt-ipam needs PostgreSQL 16 or newer. If the existing cluster is older, either upgrade it, or point jt-ipam at a different one: set POSTGRES_HOST / POSTGRES_PORT in /etc/jt-ipam/backend.env and re-run the install. jt-ipam には PostgreSQL 16 以上が必要です。既存クラスタが古い場合は、そのクラスタを上げるか、別のデータベースを使わせます。/etc/jt-ipam/backend.env の POSTGRES_HOST / POSTGRES_PORT を変更してインストールをやり直してください。

很新的 Ubuntu/Debian：apt-get update 在加 PGDG 之後 404 Brand-new Ubuntu / Debian: apt-get update 404s after adding PGDG 出たばかりの Ubuntu / Debian：PGDG を追加した後 apt-get update が 404 になる

PGDG 對剛發布的版本常延遲數月才提供套件。安裝腳本會先用發行版自帶的 PostgreSQL（16/17/18 擇一），只有完全找不到才退回 PGDG。若仍失敗，手動裝發行版自帶的版本＋對應 pgvector 再重跑安裝： PGDG often lags a freshly released distro by months. The installer prefers whatever PostgreSQL (16/17/18) the distro itself ships and only falls back to PGDG. If it still fails, install the distro's own packages and re-run: PGDG は出たばかりのディストリビューションへの対応が数か月遅れることがよくあります。インストーラはまずディストリビューション同梱の PostgreSQL（16/17/18 のいずれか）を使い、見つからない場合にだけ PGDG に頼ります。それでも失敗する場合は、同梱版と対応する pgvector を手動で入れてからやり直してください。

apt-cache search --names-only '^postgresql-1[678]$'
sudo apt install -y postgresql-17 postgresql-17-pgvector
sudo rm -f /etc/apt/sources.list.d/pgdg.list && sudo apt-get update

Node.js install failed or too old（需要 22 以上）/升級時出現「Node.js 22 could not be installed」 Node.js install failed or too old (need >= 22) / "Node.js 22 could not be installed" during an upgrade Node.js install failed or too old（22 以上が必要）/アップグレードで「Node.js 22 could not be installed」

Node.js 22 LTS 只用來建置前端，安裝與升級都會自動從 NodeSource 裝好。裝不起來時（連不到 deb.nodesource.com、走代理、apt 衝突），安裝會停下來；升級則沿用既有的 Node 20 以上版本建置、照常完成並印出警告框，doctor 會持續提醒。手動裝好後重跑同一個指令： Node.js 22 LTS is only used to build the frontend; install and upgrade both get it from NodeSource automatically. When that fails (no access to deb.nodesource.com, a proxy, an apt conflict), install stops, while upgrade builds with an existing Node 20 or newer, finishes with a warning banner, and doctor keeps reporting it. Install it by hand and re-run the same command: Node.js 22 LTS はフロントエンドのビルドにだけ使い、インストールでもアップグレードでも NodeSource から自動で導入します。導入できない場合（deb.nodesource.com に届かない、プロキシ、apt の競合）、インストールは止まり、アップグレードは既存の Node 20 以降でビルドして完了し、警告枠を出します。doctor も指摘し続けます。手動で導入してから同じコマンドをやり直してください。

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo bash -
sudo apt-get install -y nodejs
node -v      # v22.x
sudo bash /opt/jt-ipam/scripts/jt-ipam.sh upgrade      # (or: install)

機器上原本有發行版的舊 node 時要先移除，否則 PATH 會取到舊的：sudo apt-get purge -y nodejs libnode-dev，再裝一次。 If the distro's old node is present, purge it first or PATH will keep finding it: sudo apt-get purge -y nodejs libnode-dev, then install again. ディストリビューション同梱の古い node が入っていると PATH がそちらを拾い続けます。先に sudo apt-get purge -y nodejs libnode-dev で削除してから入れ直してください。

pnpm is required to build the frontend / /usr/local/bin/pnpm: No such file or directory pnpm is required to build the frontend pnpm is required to build the frontend / /usr/local/bin/pnpm: No such file or directory

sudo npm install -g pnpm@9        # または: curl -fsSL https://get.pnpm.io/install.sh | sh -
pnpm --version
sudo bash /opt/jt-ipam/scripts/jt-ipam.sh install …   # 同じコマンドを再実行

LXC 容器裡 ping 不通/掃描代理探測不到任何主機 Inside an LXC container ping never works / the scan agent finds nothing LXC コンテナ内で ping が通らない/スキャンエージェントが何も見つけられない

容器裡 net.ipv4.ping_group_range 是唯讀的（核心屬於宿主），寫 /etc/sysctl.d/ 不會生效；setcap 那條路又會被 unit 的 NoNewPrivileges=yes 無聲擋掉。可行的是 systemd drop-in 的 ambient capability，安裝與升級都會自動套用並讀回驗證： In a container net.ipv4.ping_group_range is read-only (the kernel belongs to the host), so /etc/sysctl.d/ has no effect, and the setcap route is silently defeated by the unit's NoNewPrivileges=yes. What works is a systemd drop-in granting an ambient capability; install and upgrade both apply it and read it back: コンテナ内では net.ipv4.ping_group_range は読み取り専用です（カーネルはホストのもの）。したがって /etc/sysctl.d/ に書いても効きません。setcap を使う方法も、ユニットの NoNewPrivileges=yes によって黙って無効化されます。有効なのは systemd の drop-in で ambient capability を与える方法で、インストール時もアップグレード時も自動的に適用し、実際に付いたかを読み戻して確認します。

sudo systemctl show jt-ipam-backend -p AmbientCapabilities
# cap_net_raw が含まれていれば OK。無ければ upgrade を一度流せば付きます
sudo bash /opt/jt-ipam/scripts/jt-ipam.sh upgrade --no-pull

不需要動 Proxmox 宿主，非特權容器也適用。 No change on the Proxmox host is needed; this works for unprivileged containers too. Proxmox ホスト側を変更する必要はなく、非特権コンテナでも機能します。

大子網路（例如 10.0.0.0/8）一設定掃描，設備就都變離線、代理超載 A large subnet (for example 10.0.0.0/8) makes every device go offline and the agent overloaded 大きなサブネット（例：10.0.0.0/8）をスキャンすると機器がすべてオフラインになり、エージェントが過負荷になる

不要為了掃描把子網路切小，照實際遮罩登記就好。子網路編輯的「掃描範圍」保持「自動」：4,096 個位址以內照舊全掃；更大的子網路，已登記的 IP 與最近 7 天 ARP 看過的位址每一輪都掃（上線狀態準確），其餘位址每輪在背景探索 1,024 個來找新設備，不算進負載。需要掃描代理 1.18.0 以上（代理會自動更新）；舊代理會照舊整段輪替，負載面板會提示。如果選了「整個子網路」，/8 每輪只掃得到 4,096 個，繞一圈要好幾天，設備會在兩次掃描之間被判成離線。 Do not split the subnet for scanning; register it with its real mask. Keep the subnet's "Scan scope" at Automatic: subnets up to 4,096 addresses are swept as before; for larger ones, registered IPs and addresses seen in ARP in the last 7 days are scanned every cycle (so online status stays accurate) and the rest are explored in the background, 1,024 per cycle, to find new devices, without counting toward the load. This needs scan agent 1.18.0 or later (agents update themselves); older agents keep rotating through the whole subnet and the load panel says so. With "Whole subnet", a /8 is covered 4,096 addresses per cycle, so one pass takes days and devices show offline between scans. スキャンのためにサブネットを分割する必要はありません。実際のマスクで登録してください。サブネット編集の「スキャン範囲」は「自動」のままにします：4,096 アドレス以下は従来どおり全スキャン、それより大きいサブネットは登録済みの IP と過去 7 日間に ARP で見えたアドレスを毎周スキャンし（オンライン状態は正確）、残りは毎周 1,024 個ずつバックグラウンドで探索して新しい機器を見つけます（負荷には数えません）。スキャンエージェント 1.18.0 以降が必要です（自動更新されます）。古いエージェントはサブネット全体を分割巡回し、負荷パネルにその旨が表示されます。「サブネット全体」を選ぶと /8 は毎周 4,096 個しかスキャンできず、1 巡に数日かかるため、スキャンの間に機器がオフラインと判定されます。

主機名稱是哪裡來的？NetBIOS 名稱和主機名稱不一樣 Where did this hostname come from? The NetBIOS name differs from the host name このホスト名はどこから来たのか？NetBIOS 名とホスト名が違う

IP 頁的「主機名稱來源」把每個來源分開列出，滑過標籤看得到是哪一台掃描代理或哪個整合回報的、最後一次什麼時候看到；超過一天沒人回報的會標出幾天前，和目前採用的名稱不同的標成黃色。實際顯示哪一個由「管理 → 名稱/ARP 來源順序」決定，也可以在 IP 上固定某個來源。掃描代理只有勾了 rdns、netbios、mdns 才會查名字（只開 ICMP、ARP 時名字一定來自整合）；NetBIOS 名稱最多 15 字而且全大寫，和 DNS 名稱可以不同；mDNS 只在同一個二層網段有效，Windows 要 Server 2019、Windows 10 1703 之後才會回應；NetBIOS 是 UDP 137，Windows 防火牆的「檔案及印表機共用（NB-Name-In）」預設只允許本機子網路。 The IP page's hostname sources list every source separately; hover a tag to see which scan agent or integration reported it and when it was last seen. Names nobody has reported for a day or more show how many days ago, and names that differ from the one in use are highlighted. Which one is shown is decided by Admin → Name / ARP source order, and you can pin a source on an IP. Scan agents only look up names when rdns, netbios or mdns is ticked (with only ICMP and ARP, names come from integrations). A NetBIOS name is at most 15 characters, upper case, and can differ from the DNS name; mDNS only works within one layer-2 segment and Windows answers it from Server 2019 and Windows 10 1703 on; NetBIOS uses UDP 137, which the Windows Firewall rule "File and Printer Sharing (NB-Name-In)" allows only from the local subnet by default. IP ページの「ホスト名のソース」はソースごとに分けて表示します。タグにカーソルを合わせると、どのスキャンエージェントまたは連携が報告したか、最後に確認した日時が分かります。1 日以上報告のない名前は何日前かを表示し、使用中の名前と異なるものは黄色で示します。表示される名前は「管理 → 名称/ARP のソース順」で決まり、IP ごとにソースを固定することもできます。スキャンエージェントが名前を調べるのは rdns・netbios・mdns を選んだときだけです（ICMP と ARP のみなら名前は連携から来ています）。NetBIOS 名は最大 15 文字・大文字で、DNS 名と異なることがあります。mDNS は同じレイヤー 2 セグメント内でのみ有効で、Windows は Server 2019・Windows 10 1703 以降で応答します。NetBIOS は UDP 137 を使い、Windows ファイアウォールの「ファイルとプリンターの共有（NB-Name-In）」は既定でローカルサブネットからのみ許可します。

OCS 的最後盤點時間差了幾個小時（甚至在未來） OCS last inventory times are off by hours (or in the future) OCS の最終インベントリ日時が数時間ずれる（未来になる）

OCS 的 LASTDATE 是 OCS 主機的本地時間、沒有時區。到「管理 → 外部系統整合 → OCS」編輯整合，把「OCS 時區」設成 OCS 主機的時區（新建的整合預設跟 jt-ipam 主機相同，升級前就有的是 UTC）。換算後有盤點時間落在未來時，整合清單的「最後錯誤」欄會提醒。已經寫入的時間在每台電腦下次盤點時自動更正。 OCS stores LASTDATE in the OCS host's local time without a zone. Edit the integration under Admin → External integrations → OCS and set "OCS time zone" to the OCS host's time zone (new integrations default to the jt-ipam host's, ones created before the upgrade are UTC). When converted inventory times land in the future, the "Last error" column of the integration list says so. Times already stored correct themselves at each computer's next inventory. OCS の LASTDATE は OCS ホストのローカル時刻で、タイムゾーンを持ちません。「管理 → 外部システム連携 → OCS」で連携を編集し、「OCS のタイムゾーン」を OCS ホストのタイムゾーンにしてください（新しい連携の既定は jt-ipam ホストと同じ、アップグレード前からある連携は UTC）。換算後の日時が未来になると、連携一覧の「直近のエラー」欄に表示されます。保存済みの日時は各 PC の次回インベントリで自動的に直ります。

排程 AI 巡檢沒有跑，或跑到一半就停了 The scheduled AI review did not run, or stopped halfway 定期 AI 点検が実行されない、または途中で止まった

排程巡檢由 jt-ipam-ai-audit.timer 每 5 分鐘檢查一次是否到了設定的時刻。每個時刻只嘗試一次：開始打 LLM 時就記下這次嘗試，所以途中 LLM 主機掛掉或連不上，不會每 5 分鐘重跑，而是等下一個時刻；手動巡檢正在跑時，排程這次會略過。先確認計時器在跑，再看巡檢的紀錄。 The scheduled review is checked every 5 minutes by jt-ipam-ai-audit.timer against the configured times. Each time slot is tried once: the attempt is recorded as soon as the LLM is called, so if the LLM host goes down or cannot be reached partway, the review is not retried every 5 minutes but waits for the next slot; while a manual review is running, the scheduled one skips. Check that the timer is running, then read the review's log. 定期点検は jt-ipam-ai-audit.timer が 5 分ごとに設定した時刻を過ぎたかを確認します。各時刻は 1 回だけ試行します。LLM を呼び出す時点で試行を記録するため、途中で LLM ホストが落ちたり接続できなくなったりしても 5 分ごとに再実行せず、次の時刻を待ちます。手動の点検が実行中なら、定期点検は今回スキップします。まずタイマーが動いていることを確認し、点検のログを見てください。

systemctl status jt-ipam-ai-audit.timer
sudo journalctl -u jt-ipam-ai-audit -n 100 --no-pager

腳本說 Done，但好像什麼都沒在跑 The installer said "Done" but nothing seems to be running スクリプトは Done と言うのに何も動いていない

先跑 doctor（見最上面）。手動確認： Run doctor first (top of this page). By hand: まず doctor（このページの冒頭）を実行します。手作業で確認するなら次のとおりです。

ls -l /etc/jt-ipam/backend.env                 # 設定ファイルはあるか
ls -l /opt/jt-ipam/frontend/dist/index.html    # フロントエンドはビルドされたか
sudo systemctl status jt-ipam-backend
sudo ss -ltnp | grep -E '8000|8443|443'

瀏覽器打不開，因為預設埠是 8443 不是 443 Nothing opens: the default port is 8443, not 443 ブラウザで開けない：既定のポートは 443 ではなく 8443 です

--tls-mode self-signed / direct 由 uvicorn 自己處理 HTTPS，網址是 https://<你的 FQDN>:8443/，這個模式不需要另外裝 nginx 或 apache。 With --tls-mode self-signed / direct, uvicorn terminates TLS itself and the URL is https://<your-fqdn>:8443/. In this mode you do not need nginx or apache. --tls-mode self-signed / direct では uvicorn 自身が TLS を終端し、URL は https://<FQDN>:8443/ になります。このモードでは nginx も apache も不要です。

sudo ss -ltnp | grep 8443
curl -kI https://127.0.0.1:8443/     # HTTP/1.1 200 が返れば OK

要改用 443，安裝時加 --bind-port 443（安裝腳本會一併授予特權埠所需的能力）。 To use 443, pass --bind-port 443 at install time (the installer also grants the capability a privileged port needs). 443 を使うにはインストール時に --bind-port 443 を指定します（特権ポートに必要な capability もインストーラが付与します）。

用 IP 連進去看到「Welcome to nginx」 Browsing by IP shows "Welcome to nginx" IP でアクセスすると「Welcome to nginx」が出る

apt 會啟用 nginx 的 default 站台，把以 IP 連入的請求接走。0.3.1 起安裝腳本會自動處理；舊機器手動修： apt enables nginx's default site, which grabs IP-only access. Handled automatically since 0.3.1; on an older box: apt は nginx の default サイトを有効にするため、IP でのアクセスがそちらに吸われます。0.3.1 以降は自動で処理しますが、古い環境では手動で直します。

sudo rm /etc/nginx/sites-enabled/default
sudo sed -i 's|listen 80;|listen 80 default_server;|; s|listen 443 ssl http2;|listen 443 ssl http2 default_server;|' \
     /etc/nginx/sites-available/jt-ipam
sudo nginx -t && sudo systemctl reload nginx

nginx 回 502 Bad Gateway nginx returns 502 Bad Gateway nginx が 502 Bad Gateway を返す

後端預設監聽 127.0.0.1:8000。確認服務是 active，且 nginx 站台的 upstream 指的是同一個位址與埠。 The backend listens on 127.0.0.1:8000 by default. Confirm the service is active and that the nginx site's upstream points at the same address and port. バックエンドの既定の待ち受けは 127.0.0.1:8000 です。サービスが active であること、nginx 側の upstream が同じアドレスとポートを指していることを確認してください。

sudo systemctl status jt-ipam-backend --no-pager
grep -n proxy_pass /etc/nginx/sites-available/jt-ipam

nginx 警告 ssl_stapling ignored, issuer certificate not found nginx warns: ssl_stapling ignored, issuer certificate not found nginx が ssl_stapling ignored, issuer certificate not found と警告する

自簽憑證沒有簽發鏈，無法做 OCSP stapling，這是無害警告，換成正式憑證或 Let's Encrypt 後就不會再出現。 A self-signed certificate has no issuer chain, so OCSP stapling cannot work. Harmless; it disappears once you install a real certificate. 自己署名証明書には発行者チェーンが無いため OCSP stapling は動きません。無害な警告で、正式な証明書に入れ替えれば出なくなります。

預設帳號密碼是什麼？ What are the default credentials? 既定のアカウントとパスワードは？

沒有預設密碼。全新安裝會建立 admin 並產生隨機密碼，在安裝結束時印出一次，同時寫進只有 root 讀得到的檔案： There are none. A fresh install creates admin with a random password, prints it once at the end, and writes it to a root-only file: 既定のパスワードはありません。新規インストール時に admin を作成してランダムなパスワードを生成し、終了時に一度だけ表示するとともに、root だけが読めるファイルに保存します。

sudo cat /etc/jt-ipam/.admin-initial-password

密碼忘了/帳號被鎖住 Forgot the password / locked out パスワードを忘れた/アカウントがロックされた

用 CLI 重設同一個管理員（--force-update 才是覆寫既有帳號；不加會因為帳號已存在而報錯）： Reset the same admin from the CLI (--force-update is what overwrites an existing account; without it the command errors because the user exists): CLI から同じ管理者を再設定します（既存アカウントを上書きするのは --force-update です。付けないと「すでに存在する」というエラーになります）。

ADMIN_PW=$(openssl rand -base64 24)
sudo -u jtipam bash -c "cd /opt/jt-ipam/backend; set -a; source /etc/jt-ipam/backend.env; set +a; \
  .venv/bin/python -m app.cli.bootstrap create-admin --username admin \
  --email admin@localhost --password-stdin --force-update" <<<"$ADMIN_PW"
echo "$ADMIN_PW"

密碼至少 12 個字元。多次登入失敗造成的鎖定會隨重設一併解除。 Passwords must be at least 12 characters. A lockout from repeated failed logins is cleared by the reset. パスワードは 12 文字以上が必要です。ログイン失敗の繰り返しによるロックも、この再設定で解除されます。

登入之後一直要我先設定雙因素驗證 After signing in I am asked to set up two-factor authentication first ログインすると先に二要素認証の設定を求められる

管理員在「使用者 → 登入安全」把雙因素驗證設成「管理員必須使用」或「所有人必須使用」。還沒設定的人不會被鎖在外面：輸入密碼之後先用驗證器 App 掃描 QR code、輸入一組驗證碼，接著拿到 10 組復原碼（每組只能用一次，請存在密碼管理器等安全的地方），完成之後才進入系統。被要求的人不能自行停用雙因素驗證。SSO（OIDC / SAML）登入預設交給身分提供者自己的多因素驗證，除非管理員另外打開「SSO 登入也要求」。 An administrator set two-factor authentication to "Required for administrators" or "Required for everyone" under Users → Sign-in security. People who have not set it up are not locked out: after the password they scan a QR code with an authenticator app, enter one code, and receive 10 recovery codes (each works once; keep them somewhere safe such as a password manager) before they get in. People it applies to cannot turn it off themselves. SSO (OIDC / SAML) sign-ins rely on the identity provider's own multi-factor authentication unless the administrator also turns on "Also require for SSO sign-ins". 管理者が「ユーザー → ログインのセキュリティ」で二要素認証を「管理者は必須」または「全員必須」にしています。未設定のユーザーが締め出されることはありません。パスワードのあと認証アプリで QR コードを読み取ってコードを 1 つ入力し、リカバリーコード 10 個（各 1 回限り。パスワードマネージャーなど安全な場所に保管）を受け取ってから入れます。対象のユーザーは自分で無効にできません。SSO（OIDC / SAML）のログインは、管理者が「SSO ログインにも適用」をオンにしない限り、ID プロバイダー側の多要素認証に任せます。

手機遺失（或換手機），復原碼也不見了 Lost (or replaced) the phone and the recovery codes are gone too スマートフォンを紛失（または機種変更）し、リカバリーコードもない

請另一位管理員到「使用者」頁，在這個人那一列按「重設雙因素驗證」：驗證器與復原碼一併清掉、所有登入撤銷，政策要求的話下次登入會重新設定。系統裡只有你一位管理員時，從主機 shell 重設（會留稽核記錄）： Ask another administrator to open Users and click "Reset two-factor authentication" on that person's row: the authenticator and recovery codes are cleared and every sign-in is revoked; if the policy requires it, they set it up again at the next sign-in. If you are the only administrator, reset it from a shell on the host (an audit record is written): 別の管理者に「ユーザー」ページでその人の行の「二要素認証をリセット」を押してもらいます。認証アプリとリカバリーコードが消去され、すべてのログインが取り消されます。ポリシーで必須なら次回ログイン時に設定し直します。管理者があなた 1 人だけの場合は、ホストのシェルからリセットします（監査記録が残ります）。

sudo -u jtipam bash -c "cd /opt/jt-ipam/backend; set -a; source /etc/jt-ipam/backend.env; set +a; \
  .venv/bin/python -m app.cli.bootstrap reset-mfa --username admin"

存檔沒生效、按鈕怪怪的、版本號還是舊的 Saves do nothing, buttons behave oddly, the version still looks old 保存が効かない・ボタンの挙動が変・バージョンが古いまま

開很久沒關的分頁還在跑舊的 JS，這是最常見的原因，不是後端沒更新。先強制重新整理（Ctrl/Cmd + Shift + R），再看版本資訊頁。 A long-lived browser tab is still running the old JS bundle; this is the usual cause, not the backend. Hard-refresh (Ctrl/Cmd + Shift + R), then check the version page. 長時間開いたままのタブが古い JS を実行し続けているのが最も多い原因で、バックエンドの問題ではありません。まずスーパーリロード（Ctrl/Cmd + Shift + R）を行い、バージョン情報ページを確認してください。

新版會自動偵測到版本更換並提示重新載入。若後端版本沒變，多半是升級時沒重啟服務：sudo systemctl restart jt-ipam-backend。 Recent versions detect a new build and prompt to reload. If the backend version did not change, the service was probably not restarted: sudo systemctl restart jt-ipam-backend. 最近のバージョンは新しいビルドを検出して再読み込みを促します。バックエンドのバージョンが変わっていない場合は、サービスが再起動されていない可能性が高いです：sudo systemctl restart jt-ipam-backend。

升級後某個整合同步一直失敗 One integration keeps failing to sync after an upgrade アップグレード後、特定の連携だけ同期が失敗し続ける

單一整合失敗不會中斷其他整合；錯誤會寫回該筆整合的 last_error，也會在通知裡出現。先看「管理 → 系統診斷」，再看同步紀錄： One failing integration no longer interrupts the others; the error is written back to that instance's last_error and raised as a notification. Check Admin → System check first, then the sync log: ひとつの連携が失敗しても他は止まりません。エラーはその連携の last_error に書き戻され、通知としても上がります。まず 管理 → システムチェック を確認し、次に同期ログを見てください。

sudo journalctl -u jt-ipam-sync -n 100 --no-pager

匯出 PDF 時說「伺服器上沒有中文字型」 PDF export says "the server has no CJK font" PDF のエクスポートで「サーバーに日本語・中国語のフォントがない」と表示される

PDF 報告由後端產生，會把中文/日文字型的子集內嵌進檔案（任何閱讀器都看得到）。安裝與升級時腳本會裝 fonts-noto-cjk，但升級當下連不到 apt 鏡像時只會警告、不會中斷升級。補裝後不必重啟（下一次匯出就會用到）；DOCX/ODT 匯出不受影響。版本資訊頁的「選用相依」可以看到目前用的是哪一套字型。 PDF reports are generated by the backend, which embeds a subset of a Chinese / Japanese font into the file (so any viewer shows it). Install and upgrade install fonts-noto-cjk, but if apt cannot reach a mirror during an upgrade it only warns and carries on. After installing it no restart is needed (the next export picks it up); DOCX / ODT exports are unaffected. The version page lists the font in use under optional components. PDF レポートはバックエンドが作成し、中国語・日本語フォントのサブセットをファイルに埋め込みます（どのビューアでも表示できます）。インストールとアップグレードで fonts-noto-cjk を入れますが、アップグレード時に apt のミラーへ接続できないと警告だけで続行します。追加したあと再起動は不要です（次のエクスポートから使われます）。DOCX/ODT のエクスポートには影響しません。使用中のフォントはバージョン情報ページの任意コンポーネントで確認できます。

sudo apt-get update && sudo apt-get install -y fonts-noto-cjk

匯出 PDF 時畫面上其他操作一起斷線，日誌有 Child process ... died Exporting a PDF drops other requests too, and the log shows Child process ... died PDF をエクスポートすると他の操作も切断され、ログに Child process ... died が出る

PDF 報告用的套件會載入 numpy，numpy 一載入就呼叫 mbind（設定自己記憶體的 NUMA 位置）。後端服務的 systemd 沙箱擋掉這類系統呼叫、而且預設是直接結束程序，同一個工作程序上的其他請求就跟著斷。jt-ipam.sh install 與 upgrade 會寫入 /etc/systemd/system/jt-ipam-backend.service.d/20-numa-syscalls.conf 放行這三個呼叫；手動部署或自己改過服務單元時，執行一次 upgrade，或照下面建立同一份檔案： The PDF library imports numpy, which calls mbind (NUMA placement of its own memory) as soon as it loads. The backend's systemd sandbox blocks that group of system calls and its default action ends the process, so other requests on the same worker are cut off. jt-ipam.sh install and upgrade write /etc/systemd/system/jt-ipam-backend.service.d/20-numa-syscalls.conf to allow these three calls; on a manual deployment or a customised unit, run an upgrade once or create the same file: PDF 用のライブラリは numpy を読み込み、numpy は読み込まれた時点で mbind（自分のメモリの NUMA 配置）を呼び出します。バックエンドの systemd サンドボックスはこの種のシステムコールを禁止しており、既定の動作はプロセスの終了なので、同じワーカー上の他のリクエストも切断されます。jt-ipam.sh install と upgrade は /etc/systemd/system/jt-ipam-backend.service.d/20-numa-syscalls.conf を作成してこの 3 つを許可します。手動で配置した場合やユニットを変更している場合は、upgrade を一度実行するか、次の内容で同じファイルを作成してください。

sudo mkdir -p /etc/systemd/system/jt-ipam-backend.service.d
printf '[Service]\nSystemCallFilter=mbind set_mempolicy get_mempolicy\n' | \
  sudo tee /etc/systemd/system/jt-ipam-backend.service.d/20-numa-syscalls.conf
sudo systemctl daemon-reload && sudo systemctl restart jt-ipam-backend

Windows DNS、Windows DHCP 測試連線出現 CERTIFICATE_VERIFY_FAILED，或連不到 5986 Windows DNS or Windows DHCP connection test shows CERTIFICATE_VERIFY_FAILED, or port 5986 is unreachable Windows DNS や Windows DHCP の接続テストで CERTIFICATE_VERIFY_FAILED が出る、または 5986 に接続できない

Windows Server 的防火牆預設只開 WinRM HTTP 5985，HTTPS 5986 預設是封鎖的，要另外建立憑證監聽與防火牆規則，而且通常是自簽憑證。所以 1.0.5 起新增的 Windows DNS、Windows DHCP 連線預設就走 HTTP 5985（內容與帳密一律以 NTLM 加密，無法加密就連線失敗、不會退回明文）；之前建立的連線維持原本的設定。還在用 5986 的話，到設定裡把「WinRM 連線」改成 HTTP（5985）即可；要走 HTTPS 5986 且是自簽憑證，就關閉「驗證 TLS 憑證」，或把簽發的 CA 匯入 jt-ipam 主機。帳號要能使用 WinRM（Remote Management Users 群組或管理員），並有對應的權限（Windows DNS 要 DnsAdmins，Windows DHCP 要 DHCP Users）。 The Windows Server firewall opens only WinRM HTTP 5985 by default and blocks HTTPS 5986, which needs a certificate listener and a firewall rule, usually with a self-signed certificate. From 1.0.5 new Windows DNS and Windows DHCP connections therefore default to HTTP 5985 (content and credentials are always NTLM-encrypted; if that is not possible the connection fails instead of falling back to clear text); connections made earlier keep their settings. If one still uses 5986, set "WinRM transport" to HTTP (5985) in its settings. To use HTTPS 5986 with a self-signed certificate, turn off "Verify TLS certificate" or import the issuing CA on the jt-ipam host. The account needs WinRM access (Remote Management Users or an administrator) and the matching rights (DnsAdmins for Windows DNS, DHCP Users for Windows DHCP). Windows Server のファイアウォールは既定で WinRM HTTP 5985 のみ開いており、HTTPS 5986 はブロックされています。HTTPS には証明書付きリスナーとファイアウォール規則が別途必要で、証明書はほとんどが自己署名です。そのため 1.0.5 から新しく作成する Windows DNS と Windows DHCP の接続は既定で HTTP 5985 を使います（内容と資格情報は常に NTLM で暗号化され、暗号化できなければ平文には戻さず接続に失敗します）。それ以前に作成した接続は設定を変えません。5986 を使っている場合は、設定の「WinRM 接続」を HTTP（5985）にしてください。自己署名証明書で HTTPS 5986 を使う場合は「TLS 証明書を検証」をオフにするか、発行元 CA を jt-ipam ホストにインポートしてください。アカウントには WinRM の利用権限（Remote Management Users または管理者）と、対応する権限（Windows DNS は DnsAdmins、Windows DHCP は DHCP Users）が必要です。

AI 對話跑了很久，最後只顯示網路錯誤，沒有答案 AI chat runs for a long time, then shows a network error instead of an answer AI チャットが長時間動いたあと、回答ではなくネットワークエラーが表示される

模型查工具、整理答案的空檔可能幾十秒沒有送出任何資料，反向代理的讀取逾時（本產品的 nginx 設定是 30 秒）一到就把連線切斷，後端其實還在算。1.0.4 起 AI 對話、IP 調查判讀與路徑追蹤在等待時每 10 秒送一則保活訊息，代理不會再因為等太久而切斷，升級即可，不必改逾時設定。jt-ipam 前面若還有自己的反向代理，請不要緩衝這些回應（nginx 用 proxy_buffering off，或保留上游送的 X-Accel-Buffering: no），否則進度會等到最後才一次出現。等了很久之後顯示的是「LLM 伺服器沒有在時限內回覆」而不是網路錯誤，則是模型本身太慢：到「管理 → LLM / AI」調高逾時，或換較小的模型。 While the model looks things up and writes the answer, the stream can send nothing for tens of seconds, and the reverse proxy's read timeout (30 seconds in the bundled nginx configuration) cuts the connection while the backend is still working. From 1.0.4 the AI chat, IP investigation narrative and traceroute send a keepalive every 10 seconds while waiting, so proxies no longer cut them off; upgrading is enough and no timeout needs to change. If you run your own reverse proxy in front of jt-ipam, do not buffer these responses (nginx: proxy_buffering off, or honour the upstream X-Accel-Buffering: no), otherwise the progress only appears at the end. If the message after a long wait is "The LLM server did not answer in time" rather than a network error, the model itself is too slow: raise the timeout under Admin → LLM / AI, or choose a smaller model. モデルがツールを調べて回答をまとめている間、数十秒間何も送られないことがあり、リバースプロキシの読み取りタイムアウト（同梱の nginx 設定では 30 秒）で接続が切られます。バックエンドはまだ処理を続けています。1.0.4 から AI チャット、IP 調査の解説、経路追跡は待機中に 10 秒ごとにキープアライブを送るため、プロキシに切られなくなりました。アップグレードするだけでよく、タイムアウトの変更は不要です。jt-ipam の前に独自のリバースプロキシがある場合は、これらの応答をバッファリングしないでください（nginx なら proxy_buffering off、または上流の X-Accel-Buffering: no に従う設定）。そうしないと進捗が最後にまとめて表示されます。長く待ったあとに出るのがネットワークエラーではなく「LLM サーバーが時間内に応答しませんでした」なら、モデル自体が遅すぎます。「管理 → LLM / AI」でタイムアウトを延ばすか、より小さいモデルを選んでください。

路由器日誌一直出現 arp: ... moved from ... to ...，異常偵測說 IP 衝突，其實是同一台主機 The router log keeps printing arp: ... moved from ... to ... and anomaly detection reports an IP conflict, but it is one host ルーターのログに arp: ... moved from ... to ... が出続け、異常検出が IP 衝突と報告するが、実は同じホスト

這是 ARP flux：一台有兩張網卡的 Linux 主機，預設（arp_ignore=0）會用任何一張網卡回答本機任何一個位址的 ARP；兩個網段又在同一個二層時，同一個 IP 就會被兩張網卡輪流回答。兩個 MAC 都已經連到同一台裝置時，異常偵測會把它列在「同一台主機多張網卡（ARP flux）」，並在「子網段混在同一個二層」列出兩個網段沒有隔離的證據。在那台主機設定下面兩行並寫進 /etc/sysctl.d/： This is ARP flux: a Linux host with two NICs answers ARP for any of its addresses on either NIC by default (arp_ignore=0), and when the two segments share one layer 2 the same IP is answered by both NICs in turn. When both MACs are linked to the same device, anomaly detection lists it under "One host on several NICs (ARP flux)" and shows the evidence that the segments are not isolated under "Subnets sharing one layer 2". Set these two lines on that host and save them under /etc/sysctl.d/: これは ARP flux です。NIC が 2 枚ある Linux ホストは既定（arp_ignore=0）で、自分のどのアドレスの ARP にもどちらの NIC でも応答します。2 つのセグメントが同じレイヤー 2 にあると、同じ IP に 2 枚の NIC が交互に応答します。両方の MAC が同じデバイスに関連付けられていれば、異常検出は「同一ホストの複数 NIC（ARP flux）」に表示し、セグメントが分離されていない証拠を「同じレイヤー 2 に複数サブネット」に表示します。そのホストで次の 2 行を設定し、/etc/sysctl.d/ に保存してください。

printf 'net.ipv4.conf.all.arp_ignore=1\nnet.ipv4.conf.all.arp_announce=2\n' | \
  sudo tee /etc/sysctl.d/90-arp-flux.conf
sudo sysctl --system

IP 衝突裡標成「疑似讀壞」的 MAC（只有一個來源、查不到廠商、由另外兩個 MAC 拼成）是設備的 ARP 表正在切換時 SNMP 讀到一半，不是另一台機器；修好 ARP flux 之後就不會再出現。 A MAC marked "Likely misread" in an IP conflict (single source, no vendor, spliced from two other MACs) is an SNMP walk that caught a device's ARP table mid-change, not another machine; it stops once the ARP flux is fixed. IP 衝突で「読み取り破損の疑い」とされた MAC（報告元 1 つ・ベンダー不明・別の 2 つの MAC をつなぎ合わせた形）は、デバイスの ARP テーブルの切り替え中に SNMP が途中まで読んだもので、別の機器ではありません。ARP flux を直せば出なくなります。

DNS 比對群組一直顯示「資料不完整」「無法比對」，或列出一整個 zone 只在其中一台 A DNS comparison group keeps showing "Incomplete data" or "Cannot compare", or lists a whole zone as present on only one server DNS 比較グループが「データ不足」「比較できません」のまま、またはゾーン全体が 1 台にしかないと表示される

jt-ipam 不會在伺服器之間同步紀錄，比對只用它已經拉回來的紀錄，所以每台成員都要拉取成功過。「資料不完整」的說明會寫出是哪一台：那台最近一次拉取失敗（到 DNS 頁看它的錯誤訊息）或從沒拉取過，修好後按它的「拉取」，群組會跟著重新比對。剛升級到這一版時，既有的紀錄要等下一輪拉取才有比對用的正規化欄位，在那之前也會顯示「資料不完整」，對每台成員按一次「拉取」即可。一整個 zone 只在部分成員上，最常見的原因是那幾台的帳號讀不到那個 zone：Technitium 逐個 zone 給權限，沒有權限的 zone 根本不會列出來（測試連線會列出讀不到的 zone）；BIND 9 要讀哪些 zone 是在伺服器設定的「Zone 清單（BIND9）」逐一列出，同一組的每台要列一樣的 zone。成員之間本來就只複寫部分 zone、或某台另外放了自己的 zone 時，在差異清單那一列按「不比對這個 zone」，或在群組設定的「不比對的 zone」列出來即可，存檔後馬上重新比對。「無法比對」表示 Unbound（OPNsense）和其他類型的伺服器在同一組：Unbound 只存主機覆寫、不是完整的 zone，只能和 Unbound 同組（其他軟體可以互相混搭，例如 Windows DNS 與 UCS）。差異一直停在「待確認」，表示沒有那筆的伺服器在寬限時間之後還沒重新拉取過：確認要等它下一次拉取（看它的拉取間隔），或直接按它的「拉取」。 jt-ipam does not sync records between the servers; the comparison uses only the records it has already pulled, so every member must have been pulled successfully. The "Incomplete data" hint names the server: its last pull failed (see its error on the DNS page) or it has never been pulled; fix it and click its Pull, and the group is compared again. Right after upgrading to this version, existing records get the normalized columns used for comparison only on the next pull, so groups show "Incomplete data" until then; click Pull once on each member. A whole zone present on only some members usually means the other members' accounts cannot read it: Technitium grants access per zone and does not list zones without permission at all (the connection test lists unreadable zones); for BIND 9 the zones to read are listed one by one under "Zones (BIND9)" in the server settings, so every member of a group needs the same list. When the servers replicate only some zones, or one of them also holds zones of its own, click "Stop comparing this zone" on that row of the difference list, or list them under "Zones not compared" in the group settings; the group is compared again when you save. A difference that stays "Pending" means the server missing it has not been pulled since the grace period ended: it is confirmed at that server's next pull (see its pull interval), or click its Pull. "Cannot compare" means Unbound (OPNsense) shares a group with another type: Unbound holds host overrides rather than full zones, so it can only be grouped with Unbound (other products can be mixed, for example Windows DNS and UCS). jt-ipam はサーバー間でレコードを同期せず、比較には取得済みのレコードだけを使うため、すべてのメンバーが一度は取得に成功している必要があります。「データ不足」の説明に該当サーバーが表示されます。直近の取得に失敗した（DNS ページでエラーを確認）か、まだ取得していないサーバーです。直して「取得」を押せばグループも再比較されます。このバージョンへアップグレードした直後は、既存レコードの比較用の正規化列が次の取得まで埋まらないため「データ不足」と表示されます。各メンバーで一度「取得」を押してください。ゾーン全体が一部のメンバーにしかない場合、多くはほかのメンバーのアカウントがそのゾーンを読めないことが原因です。Technitium はゾーンごとに権限を与え、権限のないゾーンは一覧にすら出ません（接続テストで読めないゾーンを表示します）。BIND 9 は読み取るゾーンをサーバー設定の「ゾーン（BIND9）」に 1 つずつ列挙するため、同じグループのサーバーには同じゾーンを列挙してください。一部のゾーンだけを複製している場合や、あるサーバーに独自のゾーンがある場合は、違いの一覧のその行で「このゾーンを比較しない」を押すか、グループ設定の「比較しないゾーン」に入れてください。保存するとすぐに再比較します。違いが「確認待ち」のままの場合、ないサーバーが猶予時間後にまだ取得し直されていません。そのサーバーの次の取得で確定します（取得間隔を確認）。すぐ確認したいときはそのサーバーの「取得」を押してください。「比較できません」は Unbound（OPNsense）とほかの種類のサーバーが同じグループにあることを示します。Unbound はホストオーバーライドのみで完全なゾーンではないため、Unbound 同士でしかグループにできません（ほかの製品は混在できます。例：Windows DNS と UCS）。

UCS 的 DNS 拉取失敗，錯誤是 UDM REST 404（找不到 /univention/udm/）或 403（Not in allowed groups） Pulling DNS from UCS fails with UDM REST 404 (/univention/udm/ not found) or 403 (Not in allowed groups) UCS の DNS 取得が UDM REST 404（/univention/udm/ が見つからない）または 403（Not in allowed groups）で失敗する

jt-ipam 透過 UCS 的 UDM REST API 讀 DNS，那台沒有這個 API 時，Apache 會回 404。Primary 與 Backup Directory Node 預設會裝，Replica Directory Node、或當初沒裝的就沒有。用 root 在那台執行 univention-install univention-directory-manager-rest，再用 systemctl status univention-directory-manager-rest 確認服務在跑。裝好後瀏覽 https://<UCS 主機>/univention/udm/ 應該要求登入（401），不再是 404。也可以改填 Primary Directory Node 的位址：UCS 的 DNS 資料存在 LDAP，每台 Directory Node 讀到的都一樣。裝好之後如果變成 403「Not in allowed groups」，表示帳號不在允許使用 API 的群組裡：UDM REST API 只讓 UCR 變數 directory/manager/rest/authorized-groups/* 列出的群組使用，手動裝在 Replica 上時常少了這組。到 Primary 執行 ucr search authorized-groups 對照，在那台補上同樣的設定，例如 ucr set directory/manager/rest/authorized-groups/domain-admins="cn=Domain Admins,cn=groups,$(ucr get ldap/base)"，再執行 systemctl restart univention-directory-manager-rest。 jt-ipam reads DNS through the UCS UDM REST API; when that server has no such API, Apache answers 404. Primary and Backup Directory Nodes have it by default; a Replica Directory Node, or a server where it was never installed, does not. Run univention-install univention-directory-manager-rest as root on that server, then check the service with systemctl status univention-directory-manager-rest. Afterwards https://<UCS host>/univention/udm/ should ask for a login (401) instead of 404. You can also use the Primary Directory Node's address: UCS keeps DNS data in LDAP, so every Directory Node reads the same data. If it then answers 403 "Not in allowed groups", the account is not in a group allowed to use the API: the UDM REST API only admits the groups listed in the UCR variables directory/manager/rest/authorized-groups/*, which are often missing when it was installed by hand on a Replica. Compare with ucr search authorized-groups on the Primary and add the same settings on that server, for example ucr set directory/manager/rest/authorized-groups/domain-admins="cn=Domain Admins,cn=groups,$(ucr get ldap/base)", then run systemctl restart univention-directory-manager-rest. jt-ipam は UCS の UDM REST API で DNS を読み取ります。そのサーバーに API がないと Apache が 404 を返します。Primary と Backup Directory Node には標準で入っていますが、Replica Directory Node や導入時に入れなかったサーバーにはありません。そのサーバーで root として univention-install univention-directory-manager-rest を実行し、systemctl status univention-directory-manager-rest でサービスが動いていることを確認してください。導入後に https://<UCS ホスト>/univention/udm/ を開くと、404 ではなくログイン（401）を求められます。Primary Directory Node のアドレスを指定することもできます。UCS の DNS データは LDAP にあるため、どの Directory Node から読んでも同じです。導入後に 403「Not in allowed groups」になる場合は、アカウントが API の利用を許可されたグループに入っていません。UDM REST API は UCR 変数 directory/manager/rest/authorized-groups/* に列挙されたグループだけを受け付け、Replica に手動で入れた場合はよく欠けています。Primary で ucr search authorized-groups を実行して比べ、そのサーバーに同じ設定を追加してください（例：ucr set directory/manager/rest/authorized-groups/domain-admins="cn=Domain Admins,cn=groups,$(ucr get ldap/base)"）。その後 systemctl restart univention-directory-manager-rest を実行します。

DHCP 伺服器已經加進整合，IP 清單還是顯示紅色的「非法 DHCP 伺服器」 A DHCP server is already integrated, but the IP list still shows the red "Rogue DHCP server" icon DHCP サーバーを連携に追加したのに、IP 一覧に赤い「不正な DHCP サーバー」が出たまま

紅色圖示表示掃描代理收到這個位址發出的 DHCP 回應，而它不是已知的 DHCP 伺服器。整合中的 DHCP 來源（Windows DHCP、Kea、ISC DHCP、Technitium、ISOinsight、MikroTik，以及 OPNsense、pfSense、FortiGate、Palo Alto、Check Point 防火牆）會自動算成已知，IP 清單、異常偵測與 IP 調查用的是同一份判斷。整合的主機欄位填的是名稱（例如 WinRM 用的 FQDN）時，是用這個位址 IP 記錄上的主機名稱對應：完整名稱相同，或其中一邊只寫短名稱時比第一段。主機名稱對不上（例如 IP 記錄還沒有名稱）時，把整合的主機改填 IP，或編輯這筆 IP 勾「標記為 DHCP 伺服器」。 The red icon means a scan agent received DHCP replies from this address and it is not a known DHCP server. Integrated DHCP sources (Windows DHCP, Kea, ISC DHCP, Technitium, ISOinsight, MikroTik, and OPNsense, pfSense, FortiGate, Palo Alto and Check Point firewalls) count as known automatically; the IP list, anomaly detection and IP investigation share the same check. When the integration's host field holds a name (for example the FQDN used for WinRM), it is matched against the host name on this address's IP record: the full names are equal, or the first labels are equal when one side is a short name. If the names do not match (for example the IP record has no name yet), enter the integration's host as an IP address, or edit the IP and tick "Mark as DHCP server". 赤いアイコンは、スキャンエージェントがこのアドレスからの DHCP 応答を受け取り、それが既知の DHCP サーバーではないことを示します。連携中の DHCP ソース（Windows DHCP、Kea、ISC DHCP、Technitium、ISOinsight、MikroTik、および OPNsense、pfSense、FortiGate、Palo Alto、Check Point のファイアウォール）は自動で既知として扱われ、IP 一覧・異常検知・IP 調査は同じ判定を使います。連携のホスト欄が名前（例：WinRM 用の FQDN）の場合は、このアドレスの IP レコードのホスト名と照合します。完全な名前が一致するか、片方が短い名前なら先頭のラベルが一致すれば同じとみなします。名前が一致しない場合（例：IP レコードにまだ名前がない）は、連携のホストを IP アドレスで指定するか、この IP を編集して「DHCP サーバーとして指定」にチェックを入れてください。

閘道（路由器的介面位址）不回 ping，登記後顯示紅燈 A gateway (a router's interface address) does not answer ping and shows red after it is registered ゲートウェイ（ルーターのインターフェースアドレス）が ping に応答せず、登録すると赤になる

一台路由器接好幾個 LAN 時，每個 LAN 的閘道都是它自己的介面位址，常被防火牆政策擋掉 ICMP，或掃描代理不在那個網段，探測沒有回應。路由器有接 OPNsense、pfSense、FortiGate、MikroTik 或 LibreNMS 整合的話，每輪同步會讀它啟用中的介面位址，對得到的 IP 記錄就算在線（上線判定的來源「設備介面位址」，預設採信），不用另外設定；FortiGate 的 API 管理員要能讀取系統設定（介面），讀不到時這一段只記日誌。沒有接整合的，把這些閘道 IP 掛到所屬的路由器（裝置），在 IP 編輯勾「上線狀態跟著所屬設備」：同一台設備的其他位址或 LibreNMS 回報設備在線，這些位址就跟著在線，設備掛了一起變離線。IP 詳細頁發現同一個 MAC 的另一個位址在線時，會提示並可以一鍵套用。只勾選、還沒掛設備時顯示灰色「使用中（不回應探測）」，不算離線。 When one router serves several LANs, each LAN's gateway is one of the router's own interface addresses; firewall policy often drops ICMP to them, or the scan agent is not on that subnet, so probes get no answer. If the router is connected through an OPNsense, pfSense, FortiGate, MikroTik or LibreNMS integration, every sync reads its enabled interface addresses and the matching IP records count as online (the liveness source "Device interface address", trusted by default), with nothing else to set up; a FortiGate API administrator needs read access to system settings (interfaces), otherwise that step is only logged. Without an integration, link these gateway IPs to their router (device) and tick "Liveness follows its device" when editing the IP: whenever another address of the same device, or LibreNMS, reports the device up, these addresses are online too, and they go offline with the device. The IP detail page suggests this, with a one-click apply, when another address with the same MAC is online. Ticked but with no device linked, the address shows grey "In use (does not answer probes)" instead of offline. 1 台のルーターが複数の LAN を収容する場合、各 LAN のゲートウェイはルーター自身のインターフェースアドレスで、ファイアウォールのポリシーで ICMP が落とされたり、スキャンエージェントがそのセグメントにいなかったりして応答がありません。ルーターを OPNsense、pfSense、FortiGate、MikroTik、LibreNMS のいずれかで連携していれば、同期のたびに有効なインターフェースアドレスを読み、一致する IP レコードをオンラインとします（オンライン判定の根拠「機器のインターフェースアドレス」、既定で採用）。追加の設定は不要です。FortiGate の API 管理者にはシステム設定（インターフェース）の読み取り権限が必要で、読めない場合はログに記録するだけです。連携していない場合は、これらのゲートウェイ IP を所属ルーター（機器）に紐づけ、IP の編集で「オンライン状態を所属機器に従わせる」にチェックを入れてください。同じ機器のほかのアドレスか LibreNMS が機器のオンラインを報告していればオンラインとなり、機器が落ちれば一緒にオフラインになります。IP 詳細ページは、同じ MAC のほかのアドレスがオンラインのときに提案し、ワンクリックで適用できます。チェックだけで機器が未紐づけの場合は、オフラインではなく灰色の「使用中（プローブに応答しない）」になります。

升級之後所有人都被登出、要重新登入 After the upgrade everyone was signed out and has to sign in again アップグレード後に全員がログアウトされ、ログインし直す必要がある

這是預期的，只會發生一次：1.0.6 起登入改成伺服器端的工作階段：更新用的權杖只放在瀏覽器碰不到的 HttpOnly cookie，存取權杖只留在這個分頁。舊版放在瀏覽器儲存空間裡的權杖不再被接受，最晚 15 分鐘後（舊的存取權杖到期）會回到登入頁。重新登入一次即可；之後每個人可以在右上角帳號選單的「偏好設定 → 安全 → 登入中的裝置」看到並登出自己在其他地方的登入，管理員可以在「使用者」頁強制某人登出。 This is expected and happens once: from 1.0.6 sign-in uses server-side sessions: the refresh token lives only in an HttpOnly cookie that page scripts cannot read, and the access token stays in the tab. Tokens that older versions kept in browser storage are no longer accepted, so within 15 minutes (when the old access token expires) people land on the sign-in page. Signing in once is enough; afterwards everyone can see and sign out their other sign-ins in the account menu (top right) under Preferences → Security → Signed-in devices, and administrators can sign someone out everywhere from Users. 想定どおりの動作で、一度だけ起こります。1.0.6 からログインはサーバー側のセッションになりました。更新用トークンはページのスクリプトから読めない HttpOnly cookie にだけ置かれ、アクセストークンはそのタブの中にだけ残ります。旧バージョンがブラウザのストレージに置いていたトークンは受け付けないため、遅くとも 15 分後（古いアクセストークンの期限）にログイン画面に戻ります。一度ログインし直せば十分です。以後は各自が右上のアカウントメニューの「設定 → セキュリティ → ログイン中のデバイス」で他の場所のログインを確認・ログアウトでき、管理者は「ユーザー」ページから強制ログアウトできます。

Graylog 查表（DSV）回 404 或 401 The Graylog lookup (DSV) returns 404 or 401 Graylog の参照（DSV）が 404 または 401 を返す

404：權杖在網址上，所以明文的 8088 埠預設不服務，一律回 404，只有 HTTPS 可以用。升級前就在用 DSV 的站台會保留原本的行為；新設定的話，Graylog 能信任 jt-ipam 的憑證就改用 https:// 網址，不能的話到「整合 Graylog」打開「允許明文 HTTP（8088 埠）」，並建議同時填「允許的來源位址」。有設允許的來源位址時，其他位址來的請求也一律回 404。401：權杖錯了或已過期。權杖現在有效期限，到期前會發通知；在同一頁按顯示可以看到目前的權杖（會留稽核記錄），換發之後要把新網址貼回 Graylog 的 Data Adapter。 404: the token is in the URL, so plain-HTTP port 8088 is off by default and always answers 404; only HTTPS works. Sites that already used DSV before upgrading keep their previous behaviour. For a new setup, use the https:// URL if Graylog trusts jt-ipam's certificate; otherwise turn on "Allow plain HTTP (port 8088)" under Graylog integration, preferably together with "Allowed sources". When allowed sources are set, requests from any other address also get 404. 401: the token is wrong or has expired. Tokens now expire and a notification goes out before they do; reveal the current token on the same page (an audit record is written), and after rotating it paste the new URL into Graylog's Data Adapter. 404：トークンが URL に含まれるため、平文の 8088 番ポートは既定で無効になっていて常に 404 を返し、HTTPS だけが使えます。アップグレード前から DSV を使っていたサイトは従来の動作を維持します。新しく設定する場合は、Graylog が jt-ipam の証明書を信頼できるなら https:// の URL を使い、できないなら「Graylog 連携」で「平文 HTTP を許可（8088 番ポート）」をオンにし、あわせて「許可する送信元」も設定してください。許可する送信元を設定すると、それ以外のアドレスからの要求も 404 になります。401：トークンが違うか期限切れです。トークンには有効期限があり、期限前に通知が届きます。同じページで現在のトークンを表示でき（監査記録が残ります）、再発行したら新しい URL を Graylog の Data Adapter に貼り直してください。

系統診斷說「備份加密」沒有設定 System diagnostics warns that backup encryption is not set システム診断で「バックアップの暗号化」が未設定と警告される

每日備份裡同時有資料庫與解密資料庫內機密的金鑰（backend.env），拿到備份檔就等於拿到所有整合的密碼。到「管理 → 系統設定 → 每日備份加密」設定密碼（至少 12 個字元），之後每天的備份會整包加密成一個 .jtbak 檔、明文刪除。密碼忘記就解不開，請存在這台主機以外的地方。設定了卻仍警告「最後一次備份沒有加密」，是 /usr/local/bin 裡還是升級前的備份腳本（再跑一次升級），或加密失敗（看 journalctl -u jt-ipam-backup）。還原步驟見安裝文件的「備份與還原」一節。 The daily backup holds both the database and the key that decrypts the secrets inside it (backend.env), so anyone with the backup file has every integration password. Set a passphrase (at least 12 characters) under Admin → System Settings → Daily backup encryption; from then on each day's backup becomes one encrypted .jtbak file and the plain copy is deleted. A forgotten passphrase cannot be recovered, so keep it somewhere other than this host. If it is set but the warning says the last backup was not encrypted, /usr/local/bin still has the pre-upgrade backup script (run the upgrade again) or encryption failed (see journalctl -u jt-ipam-backup). Restoring is described in the Backup & restore section of the install guide. 毎日のバックアップにはデータベースと、その中の機密を復号する鍵（backend.env）の両方が入っているため、バックアップファイルを手に入れればすべての連携のパスワードが手に入ります。「管理 → システム設定 → 日次バックアップの暗号化」でパスフレーズ（12 文字以上）を設定すると、以後は毎日のバックアップが 1 つの暗号化された .jtbak ファイルになり、平文は削除されます。パスフレーズを忘れると復号できないので、このホスト以外の場所に保管してください。設定済みなのに「最後のバックアップが暗号化されていない」と出る場合は、/usr/local/bin にアップグレード前のバックアップスクリプトが残っている（アップグレードをもう一度実行）か、暗号化に失敗しています（journalctl -u jt-ipam-backup を確認）。復元手順はインストールガイドの「バックアップと復元」を参照してください。

RDP 連 Linux（xrdp/GNOME 遠端登入）時帳密明明是對的卻說認證失敗 RDP to Linux (xrdp / GNOME Remote Login) reports a logon failure with correct credentials Linux への RDP（xrdp/GNOME リモートログイン）で、正しい資格情報なのに認証失敗になる

這只發生在 aardwolf 備用引擎：它在 NTLM 認證時不送 MIC（訊息完整性碼），而 FreeRDP 的伺服器端會強制檢查它，xrdp 與 gnome-remote-desktop 用的正是 FreeRDP 伺服器，於是一律回「帳號或密碼錯誤」。請到「管理 → 系統設定 → RDP 連線引擎」改回預設的 guacd（建議；2026-09-27 起的預設，內部用 FreeRDP 用戶端）。aardwolf 會逐步淘汰。 This only happens with the aardwolf fallback engine: it does not send the NTLM message integrity code (MIC), and the FreeRDP server enforces it; xrdp and gnome-remote-desktop are both built on that server, so they answer with a logon failure regardless of the password. Go to Admin → System Settings → RDP connection engine and switch it back to the default guacd (recommended; the default since 2026-09-27, which uses the FreeRDP client). aardwolf is being phased out. これは aardwolf 予備エンジンでのみ起きます。aardwolf は NTLM の MIC（メッセージ整合性コード）を送らず、FreeRDP のサーバー側はそれを必須としています。xrdp と gnome-remote-desktop はどちらもそのサーバーを使っているため、パスワードが正しくてもログオン失敗になります。「管理 → システム設定 → RDP 接続エンジン」で既定の guacd（推奨。2026-09-27 からの既定、内部で FreeRDP クライアントを使用）に戻してください。aardwolf は段階的に廃止予定です。Windows が相手ならどのエンジンでも接続できます。

一般不需要 FreeRDP：建議使用預設的 guacd。FreeRDP 只是備用引擎，需要額外的系統套件（約 150 MB）；選了它卻沒裝時，設定頁會列出缺哪些與安裝指令，並建議改回 guacd。也可以在安裝時加 --with-freerdp；升級時若已選用 FreeRDP 會自動補上。沒選用 FreeRDP 時，版本資訊頁會把這組套件標成「未選用此引擎」，不算缺少。Ubuntu 25.10 以後只有 freerdp3-x11。 You normally do not need FreeRDP: use the default guacd. FreeRDP is only a fallback engine and needs extra system packages (~150 MB); when it is selected but not installed, the settings page lists what is missing and the command to install it, and recommends switching back to guacd. You can also pass --with-freerdp at install time; an upgrade installs them automatically when FreeRDP is already selected. When FreeRDP is not selected, the version page shows these packages as "Engine not selected", not as missing. Ubuntu 25.10 and later only have freerdp3-x11. 通常 FreeRDP は不要です。既定の guacd をお使いください。FreeRDP は予備エンジンで、追加のシステムパッケージ（約 150 MB）が必要です。選択しているのに未導入の場合、設定ページに不足分とインストールコマンドが表示され、guacd に戻すよう案内されます。インストール時に --with-freerdp を付けることもでき、FreeRDP を選択済みならアップグレード時に自動で導入されます。FreeRDP を選択していない場合、バージョン情報ページではこれらのパッケージは「このエンジンは未選択」と表示され、不足扱いにはなりません。Ubuntu 25.10 以降は freerdp3-x11 のみです。

sudo apt-get install -y freerdp2-x11 xvfb xclip ffmpeg

連過幾十次之後，GNOME 遠端登入只剩一片黑畫面 After dozens of connections, GNOME Remote Login shows only a black screen 何十回か接続した後、GNOME リモートログインが真っ黒な画面しか出さない

被控端累積了收不掉的登入畫面工作階段。GNOME 的遠端登入每接一次就開一個新的無頭工作階段，而用戶端離線時它不一定會把那個工作階段收掉，累積到一定數量，新的連線就什麼都畫不出來。在被控端上看： The target has accumulated login-screen sessions that were never reaped. GNOME Remote Login starts a new headless session for every connection, and does not reliably end it when the client disconnects; past a certain number, new connections render nothing. Check on the target: 接続先にログイン画面のセッションが回収されずに溜まっています。GNOME のリモートログインは接続のたびに新しいヘッドレスセッションを開始しますが、クライアント切断時にそれを確実に終了しません。ある程度溜まると新規接続は何も表示されなくなります。接続先で確認してください：

loginctl list-sessions | grep gdm | wc -l
sudo loginctl terminate-user gdm     # 收掉全部登入畫面（會重新產生）end all login-screen sessions (they respawn)ログイン画面のセッションを全て終了（再生成されます）

這是被控端的行為，主控台這邊已經是先送 SIGTERM、等它好好關閉連線才收掉。要避免累積，請改用「桌面共享」：它接的是既有的工作階段，不會每次都開新的。 This is the target's behaviour; the console already sends SIGTERM and waits for a clean disconnect before reaping its own processes. To avoid the build-up, use Desktop Sharing: it attaches to the existing session instead of starting a new one each time. これは接続先側の挙動です。コンソール側は既に SIGTERM を送り、正常な切断を待ってから自プロセスを終了しています。蓄積を避けるにはデスクトップ共有をご利用ください。毎回新規に開始せず、既存のセッションに接続します。

用 FreeRDP 引擎時打不出中文/日文 Chinese or Japanese cannot be typed with the FreeRDP engine FreeRDP エンジンでは中国語・日本語が入力できない

請改用主控台工具列的「貼上」：剪貼簿這條路不受限制，中文、日文都貼得進去。直接打字時，非 ASCII 字元畫面上會出現提示，不會默默消失。 Use Paste in the console toolbar instead: the clipboard path has no such limit and handles any text. When you type one directly, the console tells you; the character is never dropped in silence. コンソールのツールバーの「貼り付け」をご利用ください。クリップボード経路にこの制限はなく、どの文字でも入力できます。直接入力した場合は画面に案内が出るため、黙って消えることはありません。

原因在被控端之外：FreeRDP 的用戶端是用一張固定的按鍵對照表把鍵盤事件翻成 RDP 事件，沒有 Unicode 鍵盤通道，因此配置上沒有的字元送不出去。這是 FreeRDP 備用引擎的限制，建議使用預設的 guacd；不論用哪個引擎，工具列的「貼上」都能輸入任何文字。 The cause is in the client, not the target: FreeRDP translates key events through a fixed key table and has no Unicode keyboard channel, so characters absent from the layout cannot be sent. This is a limit of the FreeRDP fallback engine; use the default guacd. Whatever the engine, Paste in the toolbar can enter any text. 原因は接続先ではなくクライアント側にあります。FreeRDP はキーイベントを固定のキー対応表で RDP イベントに変換しており、Unicode キーボードチャネルを持たないため、配列にない文字は送信できません。これは FreeRDP 予備エンジンの制限です。既定の guacd をお使いください。どのエンジンでも、ツールバーの「貼り付け」なら任意の文字を入力できます。

連 GNOME 遠端登入時出現「Session Already Running」，按 Force Stop 沒有反應 GNOME Remote Login shows “Session Already Running” and Force Stop does nothing GNOME リモートログインで「Session Already Running」が出て、Force Stop を押しても何も起きない

這是被控端的行為，不是主控台沒把點擊送出去：滑鼠事件確實有送達（按鈕會變成按下的樣子），但 GDM 在該使用者已有本機工作階段時停不掉它。GNOME 的遠端登入是開一個全新的無頭工作階段，本來就不能與本機工作階段並存。 This is the target's own behaviour, not a lost click: the mouse events do arrive (the button visibly takes its pressed state), but GDM cannot stop a session that the user already has on the local console. GNOME Remote Login starts a brand-new headless session, which by design cannot coexist with the local one. これは接続先側の挙動で、クリックが届いていないわけではありません（ボタンは押された表示になります）。GDM は、そのユーザーがローカルコンソールで既に持っているセッションを停止できません。GNOME のリモートログインは新しいヘッドレスセッションを開始する仕組みで、ローカルセッションとは共存できません。

想接進已經登入的那個桌面（一般的遠端協助情境），請在被控端改用「設定 → 系統 → 遠端桌面 → 桌面共享」，不要用「遠端登入」。兩者都走 RDP 3389，但桌面共享是接上現有工作階段，不會有這個對話框。 To reach the desktop that is already logged in (the usual remote-assistance case), enable Settings → System → Remote Desktop → Desktop Sharing on the target instead of Remote Login. Both speak RDP on 3389, but Desktop Sharing attaches to the existing session and never shows this dialog. すでにログイン中のデスクトップに入りたい場合（通常のリモート支援）は、接続先で 設定 → システム → リモートデスクトップ → デスクトップ共有 を有効にしてください。どちらも 3389 の RDP ですが、デスクトップ共有は既存セッションに接続するため、このダイアログは出ません。

若確定要用遠端登入，先把本機那個工作階段結束掉： If you really want Remote Login, end the local session first: どうしてもリモートログインを使う場合は、先にローカルセッションを終了してください：

loginctl list-sessions
sudo loginctl terminate-user <username>

相容 RustDesk 的網頁連線顯示「無法建立加密連線」 The RustDesk-compatible web connection says “Encryption could not be set up” RustDesk 互換の Web 接続で「暗号化接続を確立できません」と表示される

hbbs 沒有簽受控端的身分。hbbs 要有簽章用的私鑰才會簽：用工作目錄裡的金鑰檔啟動（官方 deb 的 .env 設 KEY=_，或 -k 留空、設成 _）。用 -k <公鑰字串> 啟動的 hbbs 手上沒有私鑰，永遠不簽；網頁連線不會在沒有加密的情況下連線，所以一律拒絕。改好後重新啟動 hbbs，原本的 RustDesk 客戶端不用改設定（公鑰不變）。 hbbs did not sign the device identity. hbbs signs only when it holds the private signing key: start it with the key file in its working directory (KEY=_ in the .env of the official deb, or -k empty or _). An hbbs started with -k <public key string> has no private key and never signs, and the web connection never connects without encryption, so it is always refused. Restart hbbs after the change; RustDesk clients need no change (the public key stays the same). hbbs が接続先の ID に署名していません。hbbs は署名用の秘密鍵を持っているときだけ署名します。作業ディレクトリの鍵ファイルで起動してください（公式 deb の .env で KEY=_、または -k を空か _ にする）。-k <公開鍵の文字列> で起動した hbbs は秘密鍵を持たないため署名せず、Web 接続は暗号化なしでは接続しないので常に拒否されます。変更後に hbbs を再起動してください。RustDesk クライアントの設定変更は不要です（公開鍵は変わりません）。

網頁連線連不上，同一區網用 RustDesk 程式卻連得上 The web connection fails, but the RustDesk app on the same LAN connects Web 接続はつながらないが、同じ LAN の RustDesk アプリではつながる

最常見的原因是對方電腦的 RustDesk Key 設錯（例如大小寫打錯）。Key 錯的電腦照樣能向 ID 伺服器註冊（顯示「就緒」）、照樣回報主機名稱，同一區網內的 RustDesk 程式會直接連線、不經過中繼，所以也連得上；只有走中繼時會被中繼伺服器（hbbr）拒絕，而網頁連線一定走中繼，從外網用 RustDesk 程式連也一樣會失敗。RustDesk 代理 1.1.0 起會讀 hbbr/hbbs 的日誌找出這種電腦：伺服器列顯示「Key 錯誤 N」、裝置清單標「Key 錯誤」、IP 頁說明被拒的時間，網頁連線的錯誤訊息也會直接說是對方的 Key。修法：在那台電腦的 RustDesk「設定 → 網路 → ID / 中繼伺服器」把 Key 改成跟伺服器公鑰完全相同（用複製貼上）。改好之後下一次經過中繼成功，標記就會消失。日誌不在 /var/log/rustdesk-server/ 的站台（例如自己寫 systemd unit 或用容器）可以在代理的設定檔加 JT_RD_LOG_DIR= 指到日誌目錄；按「測試」會顯示讀不讀得到。 Most often the device's RustDesk Key is wrong (for example a letter in the wrong case). A device with a wrong Key still registers with the ID server (it shows "Ready") and still reports its host name, and the RustDesk app on the same LAN connects directly without the relay, so that works too; only connections through the relay are refused by the relay server (hbbr). The web connection always uses the relay, and the RustDesk app connecting from outside fails as well. From RustDesk agent 1.1.0 the agent reads the hbbr/hbbs logs to find such devices: the server row shows "Wrong Key N", the device list marks "Wrong Key", the IP page says when it was refused, and the web connection error names the device's Key directly. Fix: on that computer, set the Key in RustDesk "Settings → Network → ID/Relay server" to exactly the server's public key (copy and paste it). The mark goes away after the next successful connection through the relay. If the logs are not in /var/log/rustdesk-server/ (a hand-written systemd unit or a container, for example), add JT_RD_LOG_DIR= with the log directory to the agent's config file; Test shows whether they can be read. 最も多い原因は、接続先の RustDesk の Key の設定ミス（大文字と小文字の打ち間違いなど）です。Key が誤っていても ID サーバーへの登録（「準備完了」と表示）やホスト名の報告はでき、同じ LAN 内の RustDesk アプリは中継を通さず直接接続するので、それもつながります。中継を通る接続だけが中継サーバー（hbbr）に拒否されます。Web 接続は必ず中継を使い、外部から RustDesk アプリで接続しても同じく失敗します。RustDesk エージェント 1.1.0 以降は hbbr/hbbs のログを読んでこうしたデバイスを見つけます。サーバー行に「Key 不一致 N」、デバイス一覧に「Key 不一致」、IP ページに拒否された時刻を表示し、Web 接続のエラーも接続先の Key が原因だと示します。対処：そのコンピューターの RustDesk「設定 → ネットワーク → ID/中継サーバー」で Key をサーバーの公開鍵と完全に同じにします（コピー＆ペースト推奨）。次に中継経由の接続が成功すると表示は消えます。ログが /var/log/rustdesk-server/ にないサイト（自作の systemd unit やコンテナなど）は、エージェントの設定ファイルに JT_RD_LOG_DIR= でログのディレクトリを指定してください。「テスト」で読めるかどうか確認できます。

主控台說「這個位址不能開主控台（本機、link-local 或保留位址）」 The console says it cannot be opened to this address (loopback, link-local or reserved) コンソールに「このアドレスにはコンソールを開けません（ループバック、リンクローカル、予約済みアドレス）」と出る

IP 記錄是有子網路寫入權限的人可以自己建的，所以主控台不連本機（127.0.0.0/8、::1）、link-local（169.254.0.0/16，含雲端中繼資料位址）、多播與保留位址，避免有人建一筆 127.0.0.1 再開主控台，把 jt-ipam 當跳板連本機的服務。私網與 CGNAT（例如 Tailscale 的 100.64.0.0/10）照常可以連。主機名稱也一樣，會先解析再檢查每一個位址。真的需要例外（例如測試環境），在 /etc/jt-ipam/backend.env 的 OUTBOUND_ALLOW_CIDRS 加入該網段後重啟 jt-ipam-backend；這個設定也會放行其他對外連線，請只加需要的網段。 Anyone who can write to a subnet can create IP records, so consoles do not connect to loopback (127.0.0.0/8, ::1), link-local (169.254.0.0/16, which includes cloud metadata addresses), multicast or reserved addresses; otherwise someone could create 127.0.0.1 and open a console to reach services on the jt-ipam host. Private ranges and CGNAT (for example Tailscale's 100.64.0.0/10) work as usual. Host names are resolved first and every address is checked. If you really need an exception (a test lab, say), add the range to OUTBOUND_ALLOW_CIDRS in /etc/jt-ipam/backend.env and restart jt-ipam-backend; it also allows other outbound connections, so add only what you need. IP レコードはサブネットへの書き込み権限があれば誰でも作れるため、コンソールはループバック（127.0.0.0/8、::1）、リンクローカル（169.254.0.0/16。クラウドのメタデータアドレスを含む）、マルチキャスト、予約済みアドレスには接続しません。そうしないと 127.0.0.1 のレコードを作ってコンソールを開き、jt-ipam ホスト上のサービスに届いてしまいます。プライベートアドレスと CGNAT（Tailscale の 100.64.0.0/10 など）は通常どおり使えます。ホスト名は先に名前解決してすべてのアドレスを確認します。どうしても例外が必要な場合（検証環境など）は、/etc/jt-ipam/backend.env の OUTBOUND_ALLOW_CIDRS にその範囲を追加して jt-ipam-backend を再起動します。ほかの外向き接続も許可されるので、必要な範囲だけにしてください。

開著的主控台突然結束，說存取權已被收回 An open console suddenly ends, saying access was revoked 開いていたコンソールが突然終了し、アクセス権が取り消されたと表示される

主控台開著的期間每 30 秒會重新確認一次：帳號仍是啟用的、開主控台的那次登入沒有被登出，以及仍有這個 IP 的連線權限。帳號被停用、被強制登出（含重設雙因素驗證）、自己在別處登出這次登入，或是 IP 被刪除、連線權限被收回時，連線會在 30 秒內結束，畫面會說明是哪一種原因，並留一筆 console_revoked 稽核記錄。原因是登出的話，重新登入之後再開即可；是權限的話，請管理員確認權限設定。 While a console is open it is re-checked every 30 seconds: the account is still active, the sign-in that opened it has not been signed out, and you still have console rights on that IP. If the account is deactivated, you are signed out (including a two-factor authentication reset), you sign that session out elsewhere, or the IP is deleted or your rights are withdrawn, the connection ends within 30 seconds, the screen says which of these happened, and a console_revoked audit record is written. If it was a sign-out, sign in again and reopen it; if it was permissions, ask an administrator to check them. コンソールを開いている間は 30 秒ごとに、アカウントが有効であること、そのコンソールを開いたログインがログアウトされていないこと、その IP への接続権限がまだあることを確認します。アカウントの無効化、強制ログアウト（二要素認証のリセットを含む）、別の場所でのそのログインのログアウト、IP の削除や接続権限の取り消しがあると、30 秒以内に接続を終了し、どの理由かを画面に表示して console_revoked の監査記録を残します。ログアウトが理由ならログインし直して開き直してください。権限が理由なら管理者に設定を確認してもらってください。

開一張 issue，附上這四樣就夠我們判斷 Open an issue: these four outputs are usually enough issue を立ててください：この四つがあれば判断できます

# 1) 版本與作業系統Version and OSバージョンと OS
cat /opt/jt-ipam/backend/app/version.py; lsb_release -ds; uname -r
# 2) 健康檢查Health check健全性チェック
sudo bash /opt/jt-ipam/scripts/jt-ipam.sh doctor
# 3) 後端日誌Backend logバックエンドのログ
sudo journalctl -u jt-ipam-backend -n 100 --no-pager
# 4) 失敗當下的完整輸出（只貼最後一行不夠）The full output of the failure (the last line alone is not enough)失敗した時の出力全文（最後の一行だけは不可）

貼之前請把主機名稱、對外網域、IP 與任何密碼/金鑰換掉。 Please redact hostnames, public domains, IP addresses and any password or key before pasting. 貼り付ける前に、ホスト名・公開ドメイン・IP アドレス・パスワードや鍵はすべて伏せてください。

github.com/jasoncheng7115/jt-ipam/issues

完整安裝與維運手冊 Full install & operations manual インストールと運用の完全な手順書

INSTALL_zh-TW.md · INSTALL.md · INSTALL_ja.md · UPGRADE_FROM_0.4.md