安裝與升級疑難排解 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（需要 18 以上） Node.js install failed or too old (need >= 18) Node.js install failed or too old（18 以上が必要）

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo bash -
sudo apt-get install -y nodejs
node -v

機器上原本有發行版的舊 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 ホスト側を変更する必要はなく、非特権コンテナでも機能します。

腳本說 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 文字以上が必要です。ログイン失敗の繰り返しによるロックも、この再設定で解除されます。

存檔沒生效、按鈕怪怪的、版本號還是舊的 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

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

請到 管理 → 系統設定 → 主控台，把 RDP 連線引擎改成 FreeRDP。預設的 aardwolf 引擎在 NTLM 認證時不送 MIC（訊息完整性碼），而 FreeRDP 的伺服器端會強制檢查它 —— xrdp 與 gnome-remote-desktop 用的正是 FreeRDP 伺服器，於是一律回「帳號或密碼錯誤」。連 Windows 目標時兩個引擎都可以。 Go to Admin → System settings → Console and switch the RDP engine to FreeRDP. The default aardwolf engine 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. Either engine works against Windows targets. 管理 → システム設定 → コンソール で RDP 接続エンジンを FreeRDP に切り替えてください。既定の aardwolf エンジンは NTLM の MIC（メッセージ整合性コード）を送らず、FreeRDP のサーバー側はそれを必須としています。xrdp と gnome-remote-desktop はどちらもそのサーバーを使っているため、パスワードが正しくてもログオン失敗になります。Windows が相手ならどちらのエンジンでも接続できます。

FreeRDP 引擎需要額外的系統套件（約 150 MB），設定頁會列出缺哪些與安裝指令。也可以在安裝時加 --with-freerdp；升級時若已選用 FreeRDP 會自動補上。 The FreeRDP engine needs extra system packages (~150 MB); the settings page lists what is missing and the command to install it. You can also pass --with-freerdp at install time — an upgrade installs them automatically when FreeRDP is already selected. FreeRDP エンジンには追加のシステムパッケージ（約 150 MB）が必要です。不足分とインストールコマンドは設定ページに表示されます。インストール時に --with-freerdp を付けることもでき、FreeRDP を選択済みならアップグレード時に自動で導入されます。

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 鍵盤通道，因此配置上沒有的字元送不出去。預設的 aardwolf 引擎沒有這個限制 —— 如果目標是 Windows，用預設引擎即可。 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. The default aardwolf engine does not have this limit — for Windows targets, the default engine is the better choice. 原因は接続先ではなくクライアント側にあります。FreeRDP はキーイベントを固定のキー対応表で RDP イベントに変換しており、Unicode キーボードチャネルを持たないため、配列にない文字は送信できません。既定の aardwolf エンジンにこの制限はなく、Windows が相手なら既定のままで十分です。

連 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>

開一張 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