オフライン / 閉域網インストール (Air-gap)

インターネットアクセスが遮断されたサイト (軍施設 / セキュリティ等級施設 / 一部の工場) にゲートウェイを導入する際の手順です。標準のクイックインストールは product.kopens.io への到達が必要ですが、閉域網ではそれができないため、 外部で成果物を取得し USB / NAS で移送してから インストールする必要があります。

コンテナモード (2026.05+、推奨)

install パッケージとコンテナイメージ tar.zst の 2 点を移送します。install.sh が sibling の image/*.tar.zst を検出すると docker load で自動 import します (registry pull を回避)。

準備 PC (インターネット可)

搬出バンドルは手作業で作らず、airgap-bundle.sh で作成します。リポジトリファイルとコンテナイメージを一括でまとめてくれるため、バージョンの不一致が発生しません。GitLab では airgap:export の手動ジョブを実行し、artifacts としてダウンロードしても構いません。

# 1) 저장소 받기
curl -fsSLO https://product.kopens.io/plantpulse-edge/plantpulse-edge-docker.tar.gz
mkdir -p plantpulse-edge-docker
tar xzf plantpulse-edge-docker.tar.gz -C plantpulse-edge-docker --strip-components=1

# 2) 반출 번들 굽기 — 저장소 + 이미지가 함께 들어간다
sudo bash plantpulse-edge-docker/bin/airgap-bundle.sh

# 3) USB / NAS 로 옮김 (파일명 예: plantpulse-edge-images-2026.07.tar.gz)
cp plantpulse-edge-images-*.tar.gz /media/usb/

閉域網ボックス (インターネットなし)

sudo -i
mkdir -p /opt/kopens/plantpulse-edge-docker
tar xzf /media/usb/plantpulse-edge-images-*.tar.gz \
    -C /opt/kopens/plantpulse-edge-docker --strip-components=1
cd /opt/kopens/plantpulse-edge-docker/repo/bin
# 필요하면 env.sh 에서 EDGE_ID / SITE_ID 를 박스별로 조정한 뒤 실행
sudo bash airgap-load.sh
# airgap-load.sh: 오프라인 Docker 설치 → 이미지 docker load → install.sh(SKIP_PULL=1)

インストール後、コンテナモードで検証します:

sudo bash /opt/kopens/install/bin/status.sh
sudo bash /opt/kopens/install/bin/health.sh
curl -ks https://127.0.0.1/api/v1/system/version | python3 -m json.tool
curl -ks https://127.0.0.1/api/v1/system/health  | python3 -m json.tool

閉域網でもインストール完了の判定基準は同一です。運用投入前に本番受入基準に従い、バックアップファイル、acceptance log、image tag、認証情報の引き渡し有無を記録してください。

(legacy) Native モードの air-gap 手順

以下の手順は 2026.05 未満の native ボックス専用です。新規展開では上記のコンテナモードを使用してください。

1. 準備物

項目	備考
インターネット接続された準備 PC	成果物ダウンロード用 (オフィス PC で可)
USB ディスク (32GB+ 推奨)	成果物 + 依存パッケージ RPM の運搬
PlantPulse 成果物	`KOPENS_EDGE_V<version>.tar.zstd` (~1GB)
`install.sh` のコピー	閉域網でも動作するよう一部修正が必要 (URL → ローカルパス)
OS RPM パッケージ	dnf がインターネットに出られない環境でもインストールできるよう事前に取得

2. 準備 PC での作業 (インターネット可)

2.1 成果物 + install.sh のダウンロード

# USB 마운트 위치
USB=/mnt/usb

# 산출물 (가장 최신 버전 — 약 1GB)
curl --proto =https --tlsv1.2 --fail \
  -o $USB/KOPENS_EDGE_V2026.tar.zstd \
  https://product.kopens.io/plantpulse-edge/KOPENS_EDGE_V2026.tar.zstd

# install.sh 도 같이 (참고용 — 폐쇄망에선 수정 후 사용)
curl --proto =https --tlsv1.2 --fail \
  -o $USB/install.sh \
  https://product.kopens.io/plantpulse-edge/install.sh

# (옵션) sha256 검증 파일
curl --proto =https --tlsv1.2 --fail \
  -o $USB/install.sh.sha256 \
  https://product.kopens.io/plantpulse-edge/install.sh.sha256 || true

2.2 OS 依存パッケージ RPM のダウンロード (Fedora 38 基準)

setup.sh が dnf でインストールするパッケージを事前にダウンロードのみ行い、USB に格納します:

# 빈 디렉토리
mkdir -p $USB/rpms
cd $USB/rpms

# setup.sh 의 dnf install 라인의 패키지 목록
PKGS="tar htop fping pv firefox java-17-openjdk-devel jna jemalloc \
      jemalloc-devel zstd curl-devel expat-devel uuid wget sysstat \
      chrony tuned net-tools numactl nodejs npm python3 fail2ban \
      gcc glibc-devel zlib-devel libstdc++-static NetworkManager-tui \
      docker-ce docker-ce-cli containerd.io \
      java-17-amazon-corretto-devel"

# 의존성 포함 다운로드 (--downloadonly + --resolve)
sudo dnf install --downloadonly --resolve --downloaddir=$USB/rpms $PKGS

2.3 install.sh の修正 (URL → ローカルパス)

# install.sh 의 다운로드 부분을 USB 경로로
sed -i 's|https://download\.kopens\.[a-z]*\.com|file:///mnt/usb|g' $USB/install.sh
sed -i 's|https://download\.kopens\.[a-z]*\.io|file:///mnt/usb|g'  $USB/install.sh
# (혹은 install.sh 내부의 `curl ... KOPENS_EDGE_*.tar.zstd` 라인을 직접 편집해 USB 경로 사용)

USB を安全に取り外します。

3. 閉域網ゲートウェイでの作業

3.1 USB マウント + RPM 一括インストール

# USB 인식
sudo mount /dev/sdb1 /mnt/usb       # 디바이스 명은 환경마다 다름

# RPM 일괄 설치 (의존성 자동 해결)
sudo rpm -Uvh --force --replacepkgs /mnt/usb/rpms/*.rpm

# (옵션) tar 보관소가 있으면 dnf 로도 가능:
#   sudo dnf install --disablerepo=* --nogpgcheck /mnt/usb/rpms/*.rpm

3.2 成果物の解凍

sudo mkdir -p /opt
cd /opt
sudo tar -I 'zstd -d' -xvf /mnt/usb/KOPENS_EDGE_V2026.tar.zstd
# /opt/kopens 에 풀림

3.3 H/W 初期化 (任意) — `tools/setup.sh` の依存パッケージ段階はスキップ

dnf install の段階は既に RPM で処理済みのため、setup.sh の一部の段階のみ 手動で実行します:

sudo -i
cd /opt/kopens/tools

# 호스트명
hostnamectl set-hostname EDGE_<number>

# env.sh 생성
cat > /opt/kopens/plantpulse-edge/conf/env.sh << EOF
export KOPENS_HOME=/opt/kopens
export PE_HOME=/opt/kopens/plantpulse-edge
export PE_DATA_DIR=/data1
export JAVA_HOME=/usr/lib/jvm/java-17-amazon-corretto
export CLEAN_ON_STARTUP=true
EOF
mkdir -p /data1

# 네트워크 (대화형)
./net/set-1.sh
./net/set-2.sh
systemctl restart NetworkManager.service

# 로케일 + 타임존
localectl set-locale LANG=ko_KR.utf8
timedatectl set-timezone Asia/Seoul

# tuned + 방화벽 + sysctl + chrony + ssl + vpn
systemctl enable --now tuned
tuned-adm profile throughput-performance
./firewall/open.sh
./file/run.sh
./ssl/gen.sh
# ./vpn/setup.sh   # 폐쇄망에선 보통 미사용

# CPU governor + hugepages
for f in /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor; do echo performance > $f; done
echo 9216 > /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages

# systemd 서비스 등록
cp /opt/kopens/tools/service/plantpulse.service /etc/systemd/system/
systemctl daemon-reload
systemctl enable plantpulse

3.4 起動

sudo systemctl start plantpulse
sleep 60          # 풀스택 부팅 대기
/opt/kopens/plantpulse-edge/bin/ps.sh
curl -s http://127.0.0.1/api/v1/system/health | jq

4. アップグレード (閉域網)

upgrade.sh の自動ダウンロードはインターネットが必要なため使用できません。手動手順:

# 1. 준비 PC 에서 새 산출물 USB 로 옮김 (위 2.1 동일)
# 2. 폐쇄망 게이트웨이에서:
sudo /opt/kopens/plantpulse-edge/bin/backup.sh

sudo /opt/kopens/plantpulse-edge/bin/stop.sh
cd /opt
sudo mv kopens kopens.old.$(date +%Y%m%d-%H%M%S)
sudo tar -I 'zstd -d' -xvf /mnt/usb/KOPENS_EDGE_V<new-version>.tar.zstd
sudo /opt/kopens/plantpulse-edge/bin/start.sh

検証後、kopens.old.* ディレクトリを保存します (またはディスク容量不足の場合は削除)。

5. よく陥る落とし穴

症状	原因 / 対処
`dnf install` がインターネットを探して停止する	`--disablerepo=*` オプションの指定漏れ。上記 3.1 のオプションをそのまま使用
`tar: Error opening archive`	USB 上の成果物が一部のみコピーされている。準備 PC で sha256 を比較後に再コピー
systemctl status plantpulse → activating	`bin/start.sh` の段階のどこかで停止。`journalctl -u plantpulse -f` でライブ確認
時刻が合わない (1970年)	閉域網で NTP に到達不可。社内 NTP サーバの IP を `/etc/chrony.conf` に追加
docker がインストールされない	RPM ダウンロード時に `docker-ce` が漏れている。Fedora の docker repo を追加して再ダウンロード
install.sh が download URL を呼び出す	`sed` の修正漏れ — install.sh 内のすべての URL を `file:///mnt/usb/...` に変更

6. さらに詳しく

インターネット利用可能な場合の標準手順: クイックインストール
legacy native インストール: (legacy) H/W フルインストール
本番受入基準: 本番受入基準
バックアップからの復旧 (災害時): バックアップ / 復旧
新バージョンの適用 (インターネット可): アップグレード (upgrade.sh)

コンテナモード (2026.05+、推奨)​

準備 PC (インターネット可)​

閉域網ボックス (インターネットなし)​

(legacy) Native モードの air-gap 手順​

1. 準備物​

2. 準備 PC での作業 (インターネット可)​

2.1 成果物 + install.sh のダウンロード​

2.2 OS 依存パッケージ RPM のダウンロード (Fedora 38 基準)​

2.3 install.sh の修正 (URL → ローカルパス)​

3. 閉域網ゲートウェイでの作業​

3.1 USB マウント + RPM 一括インストール​

3.2 成果物の解凍​

3.3 H/W 初期化 (任意) — tools/setup.sh の依存パッケージ段階は スキップ​

3.4 起動​

4. アップグレード (閉域網)​

5. よく陥る落とし穴​

6. さらに詳しく​