導入流程Adoption roadmap導入ガイド

給負責把 jt-ipam 帶進公司的網管與資訊主管：從安裝到自動化分成六個階段，依序開啟功能。每個階段都有明確的完成標準，做完再往下走，資料在每一步都可信。For the network admins and IT leads bringing jt-ipam into an organisation: six phases from install to automation, turning features on in order. Each phase has a clear finish line, and you move on only when it is met, so the data can be trusted at every step.jt-ipam を社内に導入するネットワーク管理者と情報システム部門の責任者向けのガイドです。インストールから自動化までを 6 つのフェーズに分け、順番に機能を有効にしていきます。各フェーズには完了の目安があり、それを満たしてから次へ進むので、どの段階でもデータを信頼できます。

為什麼要分階段Why roll out in phases段階的に導入する理由

先有規劃，再讓機器補上事實Plan first, then let machines add the factsまず計画、事実は機械に補わせる

規劃是「應該如何」，掃描與整合是「實際如何」；先有規劃，落差才看得出來。The plan says how it should be; scans and integrations say how it is. Without the plan there is nothing to compare.計画は「あるべき姿」、スキャンと連携は「実際の姿」。計画がないと差が見えません。

先唯讀比對，再考慮自動建立Read-only first, auto-create laterまず読み取りで照合、自動作成は後で

整合一律唯讀；自動建立除了 LibreNMS 主 IP 之外都預設關閉。Integrations only read; auto-create is off by default except LibreNMS primary IPs.連携は読み取りのみ。自動作成は LibreNMS の主 IP 以外は既定でオフです。

每個階段都有完成標準Every phase has a finish line各フェーズに完了の目安

達到完成標準再往下；跳過的話，未授權 IP 這類偵測會一直誤報。Reach the finish line before moving on; skip it and checks such as unauthorised IPs keep raising false alarms.完了の目安を満たしてから次へ。飛ばすと未承認 IP などの検知が誤報を続けます。

jt-ipam 是集中記錄與管理的工具：它不會發放或回收位址，也不會封鎖設備。實際的發放與阻擋仍由你的 DHCP、防火牆與 NAC 負責。詳見定位說明。jt-ipam records and manages; it does not hand out or revoke addresses, and it does not block devices. Assignment and blocking stay with your DHCP, firewalls and NAC. See what it is.jt-ipam は記録と集中管理のための道具です。アドレスの払い出しや回収、機器の遮断は行いません。それらは引き続き DHCP・ファイアウォール・NAC の役割です。詳しくは位置づけをご覧ください。

導入順序圖Roadmap at a glance導入の流れ

核心：每個站台都要做Core: every site does theseコア：どのサイトでも実施 擴充：依你已有的系統與需求選擇Extend: pick by the systems you run and what you need拡張：既存のシステムと必要に応じて選択
  1. 0階段 0Phase 0フェーズ 0 安裝與安全Install and secureインストールと保護 HTTPS、管理員密碼、LDAP / SSO、群組與權限、備份HTTPS, admin password, LDAP / SSO, groups and permissions, backupsHTTPS、管理者パスワード、LDAP / SSO、グループと権限、バックアップ 約 1 天about 1 day約 1 日
  2. 1階段 1Phase 1フェーズ 1 IP 規劃成為唯一依據The IP plan becomes the source of truthIP 計画を唯一の拠り所に 區段、子網路、VLAN、VRF、匯入、位址範圍、單位、IP 申請Sections, subnets, VLANs, VRFs, import, address ranges, customers, IP requestsセクション、サブネット、VLAN、VRF、取り込み、アドレス範囲、顧客、IP 申請 約 2 天至 2 週about 2 days to 2 weeks約 2 日〜2 週間
  3. 2階段 2Phase 2フェーズ 2 探索與上線狀態Discovery and liveness検出と死活 掃描代理、上線判定、各來源最後出現、IP 異動記錄、異常偵測Scan agents, liveness, last seen by source, IP change log, anomaly detectionスキャンエージェント、死活、ソース別の最終確認、IP 変更履歴、異常検知 約 1 至 2 週about 1 to 2 weeks約 1〜2 週間
  4. 3階段 3Phase 3フェーズ 3 用整合印證現況Integrations confirm reality連携で実態を裏付け LibreNMS、防火牆、DHCP、DNS、虛擬化、Wazuh / OCS / Zabbix / RustDeskLibreNMS, firewalls, DHCP, DNS, virtualization, Wazuh / OCS / Zabbix / RustDeskLibreNMS、ファイアウォール、DHCP、DNS、仮想化、Wazuh / OCS / Zabbix / RustDesk 每個整合約 1 週about 1 week per integration連携ごとに約 1 週間
  5. 4階段 4Phase 4フェーズ 4 裝置與實體Devices and the physical layer機器と物理 機房 / 地點、機櫃、裝置、連接埠與佈線、纜線追蹤、電力Rooms / locations, racks, devices, ports and cabling, cable trace, powerサーバルーム/拠点、ラック、機器、ポートと配線、ケーブル追跡、電源 可與階段 3 並行can run alongside phase 3フェーズ 3 と並行可
  6. 5階段 5Phase 5フェーズ 5 維運與自動化Operations and automation運用と自動化 主控台、調查、通知、憑證派送、API 權杖、MCP、AI（選用）Consoles, Investigate, notifications, certificates, API tokens, MCP, AI (optional)コンソール、調査、通知、証明書、API トークン、MCP、AI（任意） 持續擴充ongoing継続的に拡張

兩種節奏：一週快速上線、一季完整導入Two paces: one week, or a full quarter2 つの進め方：1 週間か、四半期かけて

一週快速上線One-week quick start1 週間で立ち上げ（工作天）(working days)（営業日）
第 1 天Day 11 日目 第 2～3 天Days 2–32〜3 日目 第 4 天Day 44 日目 第 5 天：接一個Day 5: one source5 日目：1 つだけ
一季完整導入Full rollout over a quarter四半期で全面導入（週）(weeks)（週）
第 1～2 週Wk 1–21〜2 週 第 2～4 週Wk 2–42〜4 週 第 4～6 週Wk 4–64〜6 週 第 6～10 週Wk 6–106〜10 週 第 7～11 週Wk 7–117〜11 週 第 10～13 週Wk 10–1310〜13 週
階段Phaseフェーズ一週快速上線One-week quick start1 週間で立ち上げ一季完整導入Full quarter四半期で全面導入
0安裝與安全Install and secureインストールと保護第 1 天Day 11 日目第 1～2 週Wk 1–21〜2 週
1IP 規劃IP planIP 計画第 2～3 天Days 2–32〜3 日目第 2～4 週Wk 2–42〜4 週
2探索與上線Discovery検出と死活第 4 天Day 44 日目第 4～6 週Wk 4–64〜6 週
3整合Integrations連携第 5 天：接一個Day 5: one source5 日目：1 つだけ第 6～10 週Wk 6–106〜10 週
4裝置與實體Devices機器と物理之後Later後で第 7～11 週Wk 7–117〜11 週
5維運與自動化Operations運用と自動化之後Later後で第 10～13 週Wk 10–1310〜13 週

時間只是參考，依網段數量與資料整理的程度而定。快速上線只接一個網路來源（LibreNMS 或主要防火牆），其餘留到後面。Durations are a guide; they depend on how many networks you have and how tidy the existing data is. The quick start connects just one network source (LibreNMS or the main firewall) and leaves the rest for later.期間は目安で、ネットワークの数と既存データの整理具合によって変わります。クイックスタートではネットワーク系のソースを 1 つ（LibreNMS か主要なファイアウォール）だけ接続し、残りは後に回します。

0階段 0：安裝與安全Phase 0: install and secureフェーズ 0：インストールと保護核心coreコア

先把地基打好：資料還沒進來之前，就決定好誰能登入、誰能看什麼、壞了怎麼救回來。Lay the foundation before any data arrives: who can sign in, who sees what, and how you recover when something breaks.データを入れる前に土台を固めます。誰がログインでき、誰が何を見られ、壊れたときにどう復旧するかを決めておきます。

部署架構Deployment構成
使用者Users利用者瀏覽器browserブラウザHTTPSjt-ipamnginx後端backendバックエンドPostgreSQLRedisguacd掃描代理scan agentスキャンエージェント每天 03:30daily 03:30毎日 03:30異地備份Off-host backup別ホストへ退避保留 14 天kept 14 days14 日保持
登入Sign-inサインイン本機帳號＋TOTPlocal + TOTPローカル＋TOTPLDAP / ADOIDCSAML 2.0

設定步驟Steps設定の手順

  1. 安裝Installインストール一行指令裝好全部元件one command installs every component1 行で全部入る
  2. HTTPS換上正式憑證install a real certificate正式な証明書に差し替え
  3. 管理員Admin管理者換掉初始密碼，啟用 TOTPchange the initial password, turn on TOTP初期パスワードを変更し TOTP を有効化
  4. 登入方式Sign-inサインインLDAP / AD · OIDC · SAML
  5. 權限Access権限群組＋五個內建角色，可給到單位或子網路groups + 5 built-in roles, down to a tenant or subnetグループ＋5 つの組み込みロール、テナントやサブネット単位まで
  6. 備份Backupバックアップ啟用每日備份，複製到另一台enable the daily backup, copy it off-host日次バックアップを有効化し別ホストへ
sudo apt-get update && sudo apt-get install -y curl
curl -fsSL https://raw.githubusercontent.com/jasoncheng7115/jt-ipam/main/scripts/bootstrap.sh | sudo bash

完成標準Done when完了の目安

  • doctor 全部通過doctor is all greendoctor がすべて合格
  • 非管理員看不到沒授權的資料a non-admin sees only what they should管理者以外は許可された範囲だけ見える
  • 還原演練成功a restore drill worked復元テストが成功
  • 稽核記錄看得到登入與異動the audit log shows sign-ins and changes監査ログにサインインと変更が残る
常見地雷Common pitfallsよくある落とし穴
  • 還原需要同一把 ENCRYPTION_KEY（在 /etc/jt-ipam/backend.env）才解得開整合帳密等加密欄位。備份檔已包含這個檔案，所以異地備份要當機密保管。A restore needs the same ENCRYPTION_KEY (in /etc/jt-ipam/backend.env) to decrypt integration credentials and other encrypted fields. The backup includes that file, so treat off-site copies as secrets.復元には同じ ENCRYPTION_KEY（/etc/jt-ipam/backend.env 内）が必要で、これがないと連携の認証情報などの暗号化項目を復号できません。バックアップにはこのファイルが含まれるので、外部保管のコピーは機密として扱ってください。
  • 在 jt-ipam 前面再放一層自己的反向代理或負載平衡器時，那一層也要設同一套安全標頭；安全標頭不會自動跨過多出來的那一跳。If you put your own reverse proxy or load balancer in front, it must send the same security headers; they do not survive the extra hop on their own.jt-ipam の前段に独自のリバースプロキシやロードバランサーを置く場合、そこでも同じセキュリティヘッダーを設定してください。ヘッダーは余分な中継を自動では通り抜けません。
  • 主機規格照建議值準備（4 核心、8 GB、50 GB）：稽核記錄、IP 歷程與備份會一直成長。自架 LLM 不要和 jt-ipam 放同一台。Size the host at the recommended 4 vCPU, 8 GB and 50 GB: the audit log, IP history and backups keep growing. Do not run a self-hosted LLM on the same machine.ホストは推奨値（4 コア、8 GB、50 GB）で用意してください。監査ログ、IP の履歴、バックアップは増え続けます。自前の LLM を同じマシンで動かすのは避けてください。

相關See also関連部署DeploymentデプロイINSTALL疑難排解：doctorTroubleshooting: doctorトラブルシューティング：doctor登入問題Sign-in problemsログインの問題安全與管理Security & adminセキュリティと管理權限模型Permission model権限モデル

1階段 1：IP 規劃成為唯一依據Phase 1: the IP plan becomes the source of truthフェーズ 1：IP 計画を唯一の拠り所に核心coreコア

把「應該如何」完整建進 jt-ipam，讓它取代試算表。這一階段只靠人工與匯入，還不需要任何掃描或整合。Put the whole "what should be" into jt-ipam so it replaces the spreadsheet. This phase is manual work and imports only; no scans or integrations yet.「あるべき姿」をすべて jt-ipam に入れ、表計算を置き換えます。このフェーズは手作業と取り込みだけで、スキャンや連携はまだ使いません。

資料結構Data modelデータ構造
  • 單位Tenantテナント選用optional任意
    • 區段Sectionセクション總部、分公司…HQ, branch…本社・支社…
      • 198.51.100.0/24上層子網路parent subnet上位サブネット
        • 198.51.100.0/26實際使用in use実際に使用
          • 位址範圍Ranges範囲DHCP 集區、保留DHCP pool, reservedDHCP プール・予約
          • IP 位址IP addressesIP アドレス主機名稱、MAC、負責人hostname, MAC, ownerホスト名・MAC・担当
匯入Import取り込みCSV · 先 Dry-rundry-run first先にドライランphpIPAM
IP 指示計IP meterIP メーター使用中in use使用中保留reserved予約空著free空き

設定步驟Steps設定の手順

  1. 區段Sectionsセクション依組織、地區或用途，不要分太細by org, region or purpose; keep it coarse組織・地域・用途ごと、細かくしすぎない
  2. 單位Tenantsテナント管多家公司或客戶時先建first, if you manage several companies or clients複数の会社や顧客を扱うなら最初に
  3. VLAN · VRF有用到才建；重疊網段用 VRFonly if used; VRF for overlapping ranges使う場合だけ、重複レンジは VRF で
  4. 子網路Subnetsサブネット大網段當上層，往下切large block on top, carve below大きなブロックを上位に、その下を分割
  5. 位址範圍Ranges範囲標出 DHCP 集區與保留mark DHCP pools and reservationsDHCP プールと予約を明示
  6. 匯入Import取り込みCSV（先 Dry-run）或 phpIPAMCSV (dry-run first) or phpIPAMCSV（先にドライラン）か phpIPAM

完成標準Done when完了の目安

  • 使用率與 IP 指示計符合認知utilisation and the IP meter match reality使用率と IP メーターが実態と一致
  • 每個區段都有資料負責人every section has a data owner各セクションにデータ責任者がいる
  • 新位址都從 jt-ipam 配發new addresses come from jt-ipam新しいアドレスは jt-ipam から払い出す
  • 舊試算表已改唯讀the old spreadsheet is read-only旧スプレッドシートは読み取り専用
常見地雷Common pitfallsよくある落とし穴
  • 先建子網路再匯入：CSV 匯入是逐個子網路進行，子網路裡已經有的位址會略過。Create subnets before importing: the CSV import runs per subnet, and addresses the subnet already has are skipped.取り込みの前にサブネットを作成してください。CSV の取り込みはサブネット単位で行われ、すでにあるアドレスはスキップされます。
  • 不要把試算表裡過時的資料原樣搬進來就算數。拿不準的先標成「保留」或在備註寫明來源，階段 2 的掃描會告訴你哪些其實已經不在（失聯 IP）。Do not trust stale spreadsheet rows just because they imported. Mark doubtful ones as reserved or note their origin; phase 2 scanning will show which are really gone (ghost IPs).表計算の古い行を、取り込めたからといってそのまま信用しないでください。怪しいものは「予約」にするかメモに出どころを書いておけば、フェーズ 2 のスキャンで実際にはもう無いもの（ゴースト IP）が分かります。
  • 舊試算表的退場日期要明講並改成唯讀，否則兩邊會一直分歧。Announce a retirement date for the old spreadsheet and make it read-only, or the two will keep drifting apart.旧表計算の廃止日をはっきり伝えて読み取り専用にしてください。そうしないと両者がずっと食い違い続けます。

相關See also関連IPAM 核心Core IPAMIPAM のコア多單位管理Many companies or clients複数組織の管理CSV 匯入 APICSV import APICSV 取り込み APIphpIPAM 相容 APIphpIPAM-compatible APIphpIPAM 互換 API

2階段 2：探索與上線狀態Phase 2: discovery and livenessフェーズ 2：検出と死活核心coreコア

讓掃描代理回報「實際如何」，每個 IP 有了最後看到的時間，規劃與現況的落差開始浮現。Scan agents report what actually is: every IP gets a last-seen time and the gaps between plan and reality start to show.スキャンエージェントに「実際の姿」を報告させます。すべての IP に最終確認の時刻が付き、計画と実態の差が見え始めます。

掃描代理擺放Where agents goエージェントの配置
VLAN 10 · 192.0.2.0/24掃描代理Agentエージェント同網段：ICMP＋ARP / MAC＋廠牌same segment: ICMP + ARP / MAC + vendor同一セグメント：ICMP＋ARP / MAC＋ベンダー
路由器Routerルーター
VLAN 20 · 198.51.100.0/24跨過路由：只剩 ICMPacross a router: ICMP onlyルーター越し：ICMP のみ
上線onlineオンライン離線offlineオフライン未知unknown不明

設定步驟Steps設定の手順

  1. 本機代理Local agentローカル先指派它連得到的子網路assign the subnets it can reach届くサブネットを割り当てる
  2. 其他網段Other segments他のセグメント每段一台 Linux 裝代理，由代理主動連回one Linux host per segment; the agent dials out各セグメントの Linux に導入、エージェントから接続
  3. 掃描項目Probes探査預設只有 ICMP，再勾 ARP、NetBIOS、mDNSICMP by default; add ARP, NetBIOS, mDNS既定は ICMP、ARP・NetBIOS・mDNS を追加
  4. 上線判定Online ruleオンライン判定閾值至少是掃描週期的兩倍threshold at least twice the scan cycleしきい値はスキャン周期の 2 倍以上
  5. 異常偵測Anomalies異常検知先選整理好的子網路，再排程start with tidy subnets, then schedule整理済みのサブネットから、のちに定期実行

完成標準Done when完了の目安

  • 上線、離線、未知的比例合理online / offline / unknown ratios look rightオンライン・オフライン・不明の比率が妥当
  • 掃描代理負載沒有「過重」no agent shows “overloaded”エージェントの負荷が「過大」でない
  • 失聯、未授權、衝突 IP 逐筆處理一輪stale, unauthorised and conflicting IPs handled once失効・未承認・衝突 IP を一通り処理
常見地雷Common pitfallsよくある落とし穴
  • 代理的位置決定看得到什麼：ARP 與 MAC 只在同一個廣播網域拿得到，要知道 MAC 與廠牌，代理就要放在那個網段裡（或在那個 VLAN 有介面的主機上）；跨過路由就只剩 ICMP。Where an agent sits decides what it sees: ARP and MACs are only available inside the same broadcast domain, so to learn MACs and vendors the agent must live in that network (or on a host with an interface in that VLAN). Across a router, only ICMP is left.エージェントの設置場所で見えるものが決まります。ARP と MAC は同じブロードキャストドメイン内でしか取得できないため、MAC とメーカーを知りたいならエージェントをそのネットワーク内（またはその VLAN にインターフェースを持つホスト）に置きます。ルーターを越えると ICMP しか使えません。
  • 代理與目標之間有防火牆擋 ICMP 時，整段會看起來都離線；先確認代理到目標網段的 ICMP 是通的。A firewall that drops ICMP between agent and target makes a whole network look offline; check that ICMP from the agent reaches it first.エージェントと対象の間に ICMP を遮断するファイアウォールがあると、ネットワーク全体がオフラインに見えます。まずエージェントから対象ネットワークへ ICMP が通ることを確認してください。
  • 大子網路不要為了掃描切小，照實際遮罩登記（例如 /8）。子網路的「掃描範圍」維持「自動」：超過 4,096 個位址時，已登記的 IP 與最近 7 天 ARP 看過的位址每一輪都掃，其餘位址在背景探索；改成「整個子網路」的話，大子網路一輪只掃得到一段，設備會在兩次掃描之間被判成離線。Do not split a large subnet just for scanning; register its real mask (a /8, for example) and keep the subnet's "Scan scope" at Automatic: above 4,096 addresses, registered IPs and addresses seen in ARP in the last 7 days are scanned every cycle and the rest are explored in the background. With "Whole subnet", a large subnet is covered one chunk per cycle and devices show offline between scans.スキャンのために大きなサブネットを分割せず、実際のマスク（例：/8）で登録してください。サブネットの「スキャン範囲」は「自動」のままにします。4,096 アドレスを超えると、登録済みの IP と過去 7 日間に ARP で見えたアドレスを毎周スキャンし、残りはバックグラウンドで探索します。「サブネット全体」にすると、大きなサブネットは 1 周に一区画しかスキャンできず、スキャンの間に機器がオフラインと判定されます。
  • 「自動收錄未登錄的 IP」預設關閉，建議維持關閉：位址一旦收錄，私接的設備就不會再出現在未授權 IP 清單。"Record unregistered IPs automatically" is off by default; keep it off. Once an address is recorded, an unauthorised device no longer shows up under unauthorised IPs.「未登録の IP を自動的に記録する」は既定で無効です。無効のままを推奨します。いったん記録されると、無断で接続された機器は未許可の IP の一覧に現れなくなります。
  • OS 偵測屬於侵入性探測，可能觸發 IDS 告警；開啟前先知會資安團隊，間隔拉長。DHCP 伺服器偵測會在網段上廣播，逐個子網路決定要不要開。OS detection is an intrusive probe that may trip IDS alerts; tell your security team first and keep the interval long. DHCP server discovery broadcasts on the network, so decide per subnet.OS 検出は侵入的な探査で、IDS の警告を引き起こすことがあります。有効にする前にセキュリティ担当へ知らせ、間隔を長めにしてください。DHCP サーバーの検出はネットワーク上でブロードキャストするので、サブネットごとに判断してください。

相關See also関連掃描代理與 IPAM 核心Scan agents and core IPAMスキャンエージェントと IPAM のコア哪些來源會自己新增 IPWhich sources create IPsIP を自動作成するソース掃描代理協定Scan agent protocolスキャンエージェントのプロトコル

3階段 3：用整合印證現況Phase 3: integrations confirm realityフェーズ 3：連携で実態を裏付け擴充extension拡張

把你已經在用的系統接進來，補上掃描看不到的東西：交換器埠、閘道的 ARP、DHCP 租約、DNS 名稱、VM 與端點代理。每個整合都在「管理 → 外部系統整合」底下各自的頁面新增（已設定的整合在選單名稱後面會有標示），之後由排程自動同步（預設每 5 分鐘一輪）。Connect the systems you already run to add what scans cannot see: switch ports, gateway ARP, DHCP leases, DNS names, VMs and endpoint agents. Each integration is added on its own page under Admin → External integrations (configured ones are marked in the menu) and then synced on a schedule (every 5 minutes by default).すでに使っているシステムを接続し、スキャンでは見えないもの（スイッチのポート、ゲートウェイの ARP、DHCP リース、DNS 名、VM、端末のエージェント）を補います。各連携は「管理 → 外部システム連携」の下のそれぞれのページで追加し（設定済みの連携はメニューに印が付きます）、その後はスケジュールで自動同期されます（既定は 5 分ごと）。

從網路底層往上接Connect bottom-up下の層から順に
↑ 越上層越依賴底下的資料upper layers rely on the ones below上の層ほど下の層に依存
  1. 6Wazuh · OCS · Zabbix · RustDesk缺口清單coverage gaps未導入の洗い出し
  2. 5Proxmox VE · VMwareVM 與容器VMs and containersVM とコンテナ
  3. 4PowerDNS · BIND9 · Unbound · Windows DNS · UCS · AdGuard Home名稱names名前
  4. 3Windows DHCP · Kea · ISC DHCP動態還是固定dynamic or fixed動的か固定か
  5. 2OPNsense · pfSense · FortiGate · Palo Alto · Check Point · MikroTik閘道 ARP、租約、規則、VPNgateway ARP, leases, rules, VPNゲートウェイ ARP・リース・ルール・VPN
  6. 1LibreNMS位置：MAC、交換器埠、LLDPwhere: MAC, switch port, LLDP位置：MAC・スイッチポート・LLDP

設定步驟Steps設定の手順

  1. 唯讀帳號Read-only読み取り専用會寫回的功能要你明確開啟write-back only when you enable it書き戻しは明示的に有効化したときだけ
  2. 限定子網路Scope範囲を限定有重疊網段時每個整合都要設required per integration when ranges overlap重複レンジがあれば連携ごとに設定
  3. 上線來源Online evidenceオンラインの根拠防火牆 ARP 採信；LibreNMS ARP 不建議trust firewall ARP, not LibreNMS ARPファイアウォールの ARP は採用、LibreNMS の ARP は非推奨
  4. 一次接一個One at a time1 つずつ自動建立先關，觀察一週auto-create off, watch for a week自動作成はオフで 1 週間観察

完成標準Done when完了の目安

  • 同步成功、筆數合理syncs succeed with sensible counts同期が成功し件数が妥当
  • 抽查「各來源最後出現」都合理a spot-check of “last seen by source” looks right「ソース別の最終確認」の抜き取りが妥当
  • 拓樸圖補上存取層與骨幹the topology gains access and core layersトポロジーにアクセス層と基幹が加わる
常見地雷Common pitfallsよくある落とし穴
  • 一次接好幾個整合又同時開自動建立，事後很難分辨紀錄從哪來。一次接一個、自動建立先全關，觀察一週再逐一決定。Connecting several integrations at once with auto-create on makes it hard to tell later where records came from. One at a time, auto-create off, a week of watching, then decide each switch.複数の連携を一度に接続して自動作成も有効にすると、後からレコードの出どころが分からなくなります。1 つずつ接続し、自動作成はまず無効にして 1 週間観察してから個別に判断してください。
  • 刪除整合會收回它寫入的資料，不要用「刪掉重建」來修設定，改編輯就好。Deleting an integration removes the data it wrote, so do not delete and recreate to fix a setting; edit it.連携を削除すると、その連携が書き込んだデータも回収されます。設定を直すために削除して作り直すのではなく、編集してください。

各整合先注意Per-integration notes連携ごとの注意

  • LibreNMS「自動建立裝置主 IP」預設開啟，第一次同步前決定要不要；「依 ARP 表自動建立 IP」預設關閉。"Auto-create device primary IPs" is on by default; decide before the first sync. "Create IPs from the ARP table" is off by default.「機器の主 IP を自動作成する」は既定で有効なので、初回の同期の前に判断してください。「ARP テーブルから IP を作成する」は既定で無効です。
  • 閘道與防火牆：OPNsense、pfSense、FortiGate、Palo Alto（Beta）、Check Point（Beta）、MikroTik RouterOS（Beta）Gateways and firewalls: OPNsense, pfSense, FortiGate, Palo Alto (Beta), Check Point (Beta), MikroTik RouterOS (Beta)ゲートウェイとファイアウォール：OPNsense、pfSense、FortiGate、Palo Alto（Beta）、Check Point（Beta）、MikroTik RouterOS（Beta）pfSense 要先裝 pfSense-pkg-RESTAPI；MikroTik 通常是主路由器，較吃資源的區段預設關閉；OPNsense / pfSense 的「自動建立 IPAM 沒有的位址」預設關閉；Check Point 接的是管理伺服器（不是閘道），在 SmartConsole 建一個權限設定檔為 Read Only All、驗證方式為 API Key 的專用管理員，並在 Management API 的進階設定允許 jt-ipam 主機連線（改完要 api restart）；閘道的 DHCP、ARP、租約另外在閘道頁籤設定 Gaia 連線，唯讀角色只讀得到 DHCP 設定；ARP 表與租約預設會用寫死的讀取指令讀，要能執行指令的帳號，用唯讀角色時這兩項自動略過、不算同步失敗。pfSense needs pfSense-pkg-RESTAPI installed first; a MikroTik is usually the main router, so its heavier sections are off by default; on OPNsense / pfSense "Create addresses IPAM does not have" is off by default; Check Point connects to the management server (not the gateways): create a dedicated administrator in SmartConsole with the Read Only All permission profile and API Key authentication, and let the Management API advanced settings accept the jt-ipam host (then run api restart); gateway DHCP, ARP and leases come from a separate Gaia connection in the Gateways tab: a read-only role reads only the DHCP settings; the ARP table and leases are read by default through fixed read commands, which need an account that may run commands, and with a read-only role those two are skipped automatically without failing the sync.pfSense は先に pfSense-pkg-RESTAPI が必要です。MikroTik は通常メインのルーターなので、負荷の大きいセクションは既定で無効です。OPNsense / pfSense の「IPAM に無いアドレスを作成する」は既定で無効です。Check Point は（ゲートウェイではなく）管理サーバーに接続します。SmartConsole で権限プロファイル Read Only All、認証方式 API Key の専用管理者を作成し、Management API の詳細設定で jt-ipam ホストからの接続を許可してください（変更後は api restart）。ゲートウェイの DHCP・ARP・リースはゲートウェイタブで別途 Gaia 接続を設定します。読み取り専用ロールで読めるのは DHCP 設定だけです。ARP テーブルとリースは既定で固定の読み取りコマンドで取得し、コマンドを実行できるアカウントが必要です。読み取り専用ロールの場合この 2 つは自動的にスキップされ、同期の失敗にはなりません。
  • DHCP：Windows DHCP（Beta）、Kea DHCP、ISC DHCP、Technitium DHCPDHCP: Windows DHCP (Beta), Kea DHCP, ISC DHCP, Technitium DHCPDHCP：Windows DHCP（Beta）、Kea DHCP、ISC DHCP、Technitium DHCPISC DHCP 沒有 API，要在 DHCP 主機上裝掃描代理讀檔；Kea 要載入 lease_cmds 才拿得到租約；Windows 要能用 WinRM 連線（預設 HTTP 5985，因為 Windows Server 防火牆預設封鎖 HTTPS 5986；內容一律以 NTLM 加密）；Technitium 用只有 DHCP 檢視權限的專用帳號建立 API token。ISC DHCP has no API, so a scan agent on the DHCP host reads its files; Kea needs the lease_cmds hook for leases; Windows needs WinRM reachable (HTTP 5985 by default, because the Windows Server firewall blocks HTTPS 5986 by default; content is always NTLM-encrypted); for Technitium, create the API token with a dedicated account that only has DHCP view permission.ISC DHCP には API が無いので、DHCP ホストにスキャンエージェントを入れてファイルを読みます。Kea でリースを取得するには lease_cmds が必要です。Windows は WinRM で接続できる必要があります（既定は HTTP 5985。Windows Server のファイアウォールは既定で HTTPS 5986 をブロックしているため。内容は常に NTLM で暗号化）。Technitium は DHCP の閲覧権限だけを持つ専用アカウントで API トークンを作成します。
  • DNS：PowerDNS、BIND9、Unbound（OPNsense）、Windows DNS、Univention UCS、Technitium、AdGuard HomeDNS: PowerDNS, BIND9, Unbound (OPNsense), Windows DNS, Univention UCS, Technitium, AdGuard HomeDNS：PowerDNS、BIND9、Unbound（OPNsense）、Windows DNS、Univention UCS、Technitium、AdGuard Home預設只讀取比對；名稱要以哪個來源為準，在「管理 → 名稱/ARP 來源順序」調整。Technitium 逐個區域給權限，沒有權限的區域不會出現在清單上，新建的區域記得補上檢視權限。Windows DNS 走 WinRM，預設 HTTP 5985（內容仍以 NTLM 加密），因為 Windows Server 防火牆預設封鎖 HTTPS 5986，要用 HTTPS 得另外建立憑證監聽；用自簽憑證時關閉「驗證 TLS 憑證」。It reads and compares by default; which source wins for names is set in Admin → Name / ARP source order. Technitium grants access per zone and does not list zones the account cannot read, so remember to grant view permission on new zones. Windows DNS uses WinRM, HTTP 5985 by default (content is still NTLM-encrypted) because the Windows Server firewall blocks HTTPS 5986 by default; HTTPS needs a certificate listener of its own, and a self-signed certificate needs "Verify TLS certificate" turned off.既定では読み取りと照合のみです。名前にどのソースを優先するかは「管理 → 名称/ARP のソース順」で調整します。Technitium はゾーンごとに権限を与え、権限のないゾーンは一覧に出ないため、新しいゾーンにも閲覧権限を忘れずに与えてください。Windows DNS は WinRM を使い、既定は HTTP 5985 です（内容は NTLM で暗号化されます）。Windows Server のファイアウォールは既定で HTTPS 5986 をブロックしており、HTTPS には証明書付きリスナーが別途必要で、自己署名証明書の場合は「TLS 証明書を検証」をオフにします。
  • 虛擬化：Proxmox VE、VMware ESXi / vCenter（Beta）Virtualization: Proxmox VE, VMware ESXi / vCenter (Beta)仮想化：Proxmox VE、VMware ESXi / vCenter（Beta）「信任虛擬化取得的 IP」預設關閉；打開的話，測試機與臨時複製的 VM 也會被收錄。"Trust addresses reported by virtualization" is off by default; turned on, test machines and temporary clones get recorded too.「仮想化から報告されたアドレスを信頼する」は既定で無効です。有効にすると、テスト機や一時的に複製した VM も記録されます。
  • 端點與監控：Wazuh、OCS Inventory NG、Zabbix、RustDesk Server（開源版）Endpoints and monitoring: Wazuh, OCS Inventory NG, Zabbix, RustDesk Server (open source)端末と監視：Wazuh、OCS Inventory NG、Zabbix、RustDesk Server（オープンソース版）這些缺口清單要在 IP 規劃完整之後才有意義，否則會被沒登記的位址灌爆。RustDesk 要在 RustDesk 主機上裝專用代理。These gap lists only mean something once the IP plan is complete; otherwise unregistered addresses flood them. RustDesk needs its dedicated agent on the RustDesk host.これらの抜けの一覧は IP 計画が揃ってから意味を持ちます。そうでないと未登録のアドレスで埋め尽くされます。RustDesk は RustDesk ホストに専用エージェントが必要です。

相關See also関連整合總覽Integration map連携の全体像哪些來源會自己新增 IPWhich sources create IPsIP を自動作成するソース網路與防火牆Network & firewallsネットワークとファイアウォールDNS 與 DHCPDNS & DHCPDNS と DHCP虛擬化Virtualization仮想化資產、監控與記錄Inventory, monitoring & logs資産・監視・ログ整合一直同步失敗An integration keeps failing連携の同期が失敗し続ける

4階段 4：裝置與實體Phase 4: devices and the physical layerフェーズ 4：機器と物理擴充extension拡張

把 IP 背後的實體補齊：在哪個機房、哪一櫃哪一 U、接哪個埠、走哪條線、用哪路電。可以和階段 3 並行。Fill in the physical side behind each IP: which room, which rack and U, which port, which cable, which power feed. It can run alongside phase 3.IP の背後にある物理の情報を揃えます。どのサーバルームの、どのラックの何 U に、どのポートで、どのケーブルで、どの電源系統か。フェーズ 3 と並行できます。

從 IP 一路點到實體From an IP down to the floorIP から物理まで
地點Location拠点平面圖floor plan平面図機櫃RackラックU、正背面、層架U, front / rear, shelvesU・前背面・棚裝置Device機器LibreNMS · CSV連接埠Portポート跳接面板穿透patch pass-throughパッチ通過線路Cableケーブル纜線追蹤cable traceケーブル追跡電力Power電源配電盤 → 插座panel → outlet分電盤 → コンセント

可以和階段 3 並行can run alongside phase 3フェーズ 3 と並行可

設定步驟Steps設定の手順

  1. 地點Locations拠点在平面圖上擺放機櫃place racks on the floor plan平面図にラックを配置
  2. 機櫃RacksラックU 數、正背面；也支援層架U count, front / rear; shelves tooU 数・前背面、棚にも対応
  3. 裝置Devices機器從 LibreNMS 帶進來，其他用 CSV / xlsxfrom LibreNMS; others via CSV / xlsxLibreNMS から、ほかは CSV / xlsx
  4. 連接埠Portsポート從來源匯入；跳接面板設穿透import from source; patch panels pass throughソースから取り込み、パッチパネルは通過設定
  5. 佈線Cabling配線建立纜線，用纜線追蹤看路徑create cables, trace the pathケーブルを作成し経路を追跡
  6. 電力Power電源配電盤 → 饋線 → 插座panel → feed → outlet分電盤 → フィード → コンセント

完成標準Done when完了の目安

  • 從伺服器 IP 一路點到交換器click from a server IP through to its switchサーバーの IP からスイッチまでたどれる
  • 抽查幾櫃，與現場一致spot-checked racks match the floor抜き取りのラックが現場と一致
常見地雷Common pitfallsよくある落とし穴
  • 想一次把所有機房建完，通常會半途而廢。先做核心機房與網路設備，其餘依優先順序補。Trying to model every room at once usually stalls halfway. Start with core rooms and network gear and add the rest by priority.すべてのサーバルームを一度に作ろうとすると、たいてい途中で止まります。主要なサーバルームとネットワーク機器から始め、残りは優先度順に追加してください。
  • 佈線與電力沒有任何系統會自動回報，只能靠人維護：指定負責人，並納入上架、搬遷、汰換的變更流程。Nothing reports cabling and power automatically; people maintain them. Name an owner and make updates part of the change process for installs, moves and removals.配線と電源を自動で報告してくれるシステムはなく、人が維持するしかありません。担当者を決め、設置・移設・撤去の変更手順に更新を組み込んでください。

相關See also関連實體資產Physical assets物理資産層架Shelving棚裝置匯入 APIDevice import API機器の取り込み API機櫃圖嵌入Rack embeddingラック図の埋め込み

5階段 5：維運與自動化Phase 5: operations and automationフェーズ 5：運用と自動化擴充extension拡張

資料可信之後，讓日常工作直接在 jt-ipam 裡完成，並把它接到通知與其他系統。With data you can trust, do the daily work inside jt-ipam and connect it to notifications and other systems.データを信頼できるようになったら、日常業務を jt-ipam の中で行い、通知や他のシステムとつなぎます。

日常在 jt-ipam 完成Day-to-day in jt-ipam日常業務は jt-ipam で
主控台ConsolesコンソールSSH · SFTP · RDP · VNC · RustDesk調查Investigate調査一個 IP 的所有線索every clue for an IPIP の手がかり探測Identify探査這是什麼設備what is this device何の機器か
jt-ipam
通知Notifications通知事件 → 條件 → 動作event → condition → actionイベント → 条件 → 動作API 權杖 · MCPAPI tokens · MCPAPI トークン · MCP憑證派送Certificates証明書配布nginx · Apache · IISGraylog記錄補上主機名稱log enrichmentホスト名付与AI（選用）AI (optional)AI（任意）自備 LLMyour own LLM自前の LLM

設定步驟Steps設定の手順

  1. 主控台Consolesコンソール逐 IP 開啟 SSH、SFTP、RDP、VNC、RustDeskturn on SSH, SFTP, RDP, VNC, RustDesk per IPIP ごとに SSH・SFTP・RDP・VNC・RustDesk を有効化
  2. 調查與探測Investigate調査と探査一個 IP 的線索收在一起every clue for one IP in one place1 つの IP の手がかりを 1 か所に
  3. 通知Notifications通知事件規則：事件 → 條件 → 動作event rules: event → condition → actionイベントルール：イベント → 条件 → 動作
  4. 憑證派送Certificates証明書配布代理定期取用，失敗自動還原agents fetch; failures roll back on their ownエージェントが取得、失敗時は自動で戻す
  5. 自動化Automation自動化API 權杖、MCP、GraylogAPI tokens, MCP, GraylogAPI トークン・MCP・Graylog
  6. AI（選用）AI (optional)AI（任意）自備 LLM 伺服器bring your own LLM server自前の LLM サーバー

完成標準Done when完了の目安

  • 值班能從 IP 開主控台、用調查找原因on-call opens consoles and investigates from the IP当番が IP からコンソールと調査を使える
  • 事件規則試跑，通知送得到a test run of event rules delivers notificationsイベントルールのテストで通知が届く
  • API 權杖都有期限、權限最小API tokens expire and are least-privilegeAPI トークンに期限と最小権限がある
常見地雷Common pitfallsよくある落とし穴
  • 改用外部 OpenAI 相容服務時，子網路、主機名稱與拓樸會送到該服務；資料不能離開公司就維持自架。Switching to an external OpenAI-compatible service sends subnets, hostnames and topology to that provider; keep it self-hosted if the data must not leave.外部の OpenAI 互換サービスに切り替えると、サブネット、ホスト名、トポロジーがその事業者に送られます。データを社外に出せない場合は自前のままにしてください。
  • 嵌入模型的維度要和資料庫欄位一致（預設 768），否則語意搜尋不會報錯，只是永遠找不到東西；換模型後在設定頁按「檢查維度」。The embedding model's dimension must match the database column (768 by default); otherwise semantic search raises no error and simply never finds anything. After changing models, press "Check dimension" on the settings page.埋め込みモデルの次元はデータベースの列と一致させてください（既定 768）。一致しないと意味検索はエラーを出さず、ただ何も見つからなくなります。モデルを変えたら設定ページで「次元を確認」を押してください。
  • 升級或重啟服務會切斷進行中的主控台連線與檔案上傳，請挑維護時段進行。Upgrades and service restarts cut console sessions and file uploads in progress; schedule them in a maintenance window.アップグレードやサービスの再起動は、進行中のコンソール接続とファイルのアップロードを切断します。メンテナンスの時間帯に行ってください。
  • 憑證代理的金鑰等同它範圍內所有憑證的私鑰，要當最高機密保管。A certificate agent's key is as good as the private keys of every certificate in its scope; guard it as a top-tier secret.証明書エージェントのキーは、その範囲内のすべての証明書の秘密鍵に相当します。最高機密として保管してください。

相關See also関連瀏覽器連線管理In-browser remote consoleブラウザ内リモートコンソールBMC / SOL 設定BMC / SOL setupBMC / SOL 設定AI 助理AI assistantAI アシスタント憑證派送Certificates証明書API 權杖API tokensAPI トークンMCP事件規則Event rulesイベントルール主控台問題Console problemsコンソールの問題