Binaryモードパッチ

変更事項

今回のパッチの主な変更事項をまとめると、以下の通りです。

順番	項目	内容	備考
1	Kafkaメッセージサイズ変更、Kafka設定	メッセージを最大2GBに引き上げます。	既存の方式と同じ(config置き換え)
2	HTTPS(Nginx) gzip圧縮	応答データをgzip圧縮します。	既存の方式と同じ(http.conf置き換え)
3	onectl関連作業	シェルスクリプト → バイナリに置き換え、Dockerモードにも新規導入します。`web/backend/data/history.db` 新規ファイルが追加されます。	今回のバージョン固有の作業
4	Kafkaメモリ増加、Kafka環境変数	`.env` の `KAFKA_OPTS` 内の `MaxDirectMemorySize` が3G → 6Gに変更されます。	今回のバージョン固有の作業

共通事前準備

以降のすべてのコマンドは、以下の1行から開始します。 INSTALL_DIR は現在インストールされているexemONEインストールフォルダのパスです。 (既存の EXEMONE_HOME との混同を避けるため、パッチ作業専用の変数として分離します。)

# 実際のインストールパスに修正してください。
export INSTALL_DIR=/home/exemone/exemone
cd $INSTALL_DIR

新規パッケージファイルの配置

担当者から受け取った新規パッケージtarファイルを /tmp に配置してください。

ls -lh /tmp/exemone-pkg-*.tar.gz

新規パッケージの展開(バイナリモード)

バイナリパッケージは単一フォルダ構造で、exemone/ の直下に bins, services, scripts, onectl 等がそのまま見えます。

mkdir -p /tmp/patch
tar -zxf /tmp/exemone-pkg-*.tar.gz -C /tmp/patch

# 構造確認(bins, services, scripts, onectl 等が見える必要があります。)
ls /tmp/patch/exemone

export NEW_PKG=/tmp/patch/exemone

envファイル置き換え時の共通原則

今回のバージョンで置き換えが必要なenv系ファイル(.env, kafka.env 等)には、顧客ごとのカスタム値が入っている場合があります。置き換え前に必ず diff で差分を確認し、顧客カスタムがある場合は手動でマージしてください。

# 例
diff $INSTALL_DIR/kafka.env $NEW_PKG/kafka.env

1. バイナリ(Binary)モード

1-1. サービス停止

サービスをすべて停止し、状態を確認します。

cd $INSTALL_DIR
./onectl stop all
./onectl stat

すべて STOPPED 状態であることを確認してください。

1-2. ⭐ 今回のバージョン固有の作業(バイナリ)

⚠️ 注意: 本手順を進める前に、$INSTALL_DIR, $NEW_PKG 環境変数が必ず指定されている必要があります。

(1) onectl関連作業

既存の onectl はシェルスクリプトでしたが、今回のバージョンから実行ファイル(バイナリ)に置き換えられます。

# 既存onectlバックアップ後、新規に置き換え
mv $INSTALL_DIR/onectl $INSTALL_DIR/onectl.old
cp $NEW_PKG/onectl $INSTALL_DIR/onectl
chmod 755 $INSTALL_DIR/onectl

(2) scripts/フォルダの置き換え

非常に古いインストール環境では、現在のスクリプトの一部が欠落している場合があるため、既存フォルダをバックアップし、新規フォルダに置き換えます。

# 既存scriptsバックアップ
mv $INSTALL_DIR/scripts $INSTALL_DIR/scripts.old

# 新しいscriptsコピー
cp -a $NEW_PKG/scripts $INSTALL_DIR/scripts
chmod -R 755 $INSTALL_DIR/scripts

(3) Kafka server.propertiesの更新(顧客カスタム確認後に置き換え)

server.properties にKafkaメッセージサイズ(2GB)、socket buffer等が反映され、顧客ごとに別途チューニング値が入っている場合があるため、diff で必ず確認してから置き換えます。

# 差分確認
diff $INSTALL_DIR/services/exemone-kafka/config/kraft/server.properties \
     $NEW_PKG/services/exemone-kafka/config/kraft/server.properties

# 既存ファイルバックアップ
cp $INSTALL_DIR/services/exemone-kafka/config/kraft/server.properties \
   $INSTALL_DIR/services/exemone-kafka/config/kraft/server.properties.old

# カスタムがなければそのまま置き換え
cp $NEW_PKG/services/exemone-kafka/config/kraft/server.properties \
   $INSTALL_DIR/services/exemone-kafka/config/kraft/server.properties

# カスタムがある場合: 上記のcpの代わりにviで両方の値をマージして保存

(4) Nginx http.confの更新(顧客カスタム確認後に置き換え)

今回のバージョンで http.conf にgzip圧縮ブロックが追加されました。ただし、TLS証明書パス、proxyヘッダー、カスタムlocationブロック等、顧客ごとに修正された内容がある場合があるため、diff で必ず確認してから置き換えます。

# 差分確認
diff $INSTALL_DIR/services/exemone-https/conf.d/http.conf \
     $NEW_PKG/services/exemone-https/conf.d/http.conf

# 既存ファイルバックアップ
cp $INSTALL_DIR/services/exemone-https/conf.d/http.conf \
   $INSTALL_DIR/services/exemone-https/conf.d/http.conf.old

# カスタムがなければそのまま置き換え
cp $NEW_PKG/services/exemone-https/conf.d/http.conf \
   $INSTALL_DIR/services/exemone-https/conf.d/http.conf

参考)http.conf内の手動マージ時 — gzipブロックの追加位置と内容

カスタム内容があり直接マージする必要がある場合は、既存ファイルの server { ... } ブロック内で、ssl_* ディレクティブの直下、# proxy コメントの上に以下のブロックを追加してください。

server {
    listen 8443 ssl;
    ...
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 10m;
    ssl_prefer_server_ciphers on;

    # ↓↓↓ ここにgzipブロックを追加 ↓↓↓
    # gzip圧縮
    gzip on;
    gzip_comp_level 5;
    gzip_min_length 1024;
    gzip_vary on;
    gzip_proxied any;
    gzip_http_version 1.1;

    gzip_types
        text/plain
        text/css
        application/javascript
        application/json
        application/xml
        image/svg+xml;
    # ↑↑↑ ここまで ↑↑↑

    # proxy
    proxy_buffer_size 8k;
    proxy_buffers 16 8k;
    ...
}

(5) Kafka設定確認スクリプトの配置(補助ツール)

新規確認ツール check-config.sh が追加されます。起動後の設定値検証に使用します。

cp $NEW_PKG/services/exemone-kafka/check-config.sh \
   $INSTALL_DIR/services/exemone-kafka/check-config.sh
chmod 755 $INSTALL_DIR/services/exemone-kafka/check-config.sh

(6) .envの更新(手動マージ)

.env には初期インストール時に入力されたサイト別の値が入っているため、新規ファイルでまるごと上書きしてはいけません。diff で差分を確認した後、vi で直接編集してください。

保持する必要があるキー(上書きしないこと):

キー	例
`OS`	`OS=rocky8`
`MODE`	`MODE=exemone`

新しい値で更新する必要がある行:

項目	説明
*`EXEMONE_` サービスバージョン行**	例: `EXEMONE_API=exemone-api-v3.0.604.5-snapshot`
`KAFKA_OPTS`	`MaxDirectMemorySize=3G` → `6G`
その他新規追加行	新規ファイルに新しく追加された行をすべて反映します。

# 差分確認
diff $INSTALL_DIR/.env $NEW_PKG/.env

# バックアップ
cp $INSTALL_DIR/.env $INSTALL_DIR/.env.old

# 上記diff結果を見てviで手動マージしてください。
vi $INSTALL_DIR/.env

(7) サービスバイナリの置き換え

各サービスの実行ファイルは bins/<서비스명>/ の下にバージョンを含むファイル名(例: exemone-api-v3.0.508.204)の形で存在します。新規パッケージの bins/ 全体を既存の bins/ にコピーしますが、-n オプションで既存ファイルを上書きしないようにします。こうすることで新規バージョンのファイルのみが追加され、インフラバイナリ(kafka/postgresql/redis等)や旧バージョンのファイルはそのまま維持されます。

# exemone-frontのdistをバックアップしておきます。
export VERSION=$(cat $INSTALL_DIR/services/exemone-front/version.txt | cut -d'=' -f2 | cut -d',' -f1)

# バージョン確認
echo $VERSION

mv $INSTALL_DIR/bins/exemone-front/dist "$INSTALL_DIR/bins/exemone-front/dist_$VERSION"

# 上書きせずコピー(新規ファイルのみ追加されます。)
cp -arn $NEW_PKG/bins/. $INSTALL_DIR/bins/

# front version txt修正
mv $INSTALL_DIR/services/exemone-front/version.txt "$INSTALL_DIR/services/exemone-front/version_$VERSION.txt"

mv $NEW_PKG/services/exemone-front/version.txt $INSTALL_DIR/services/exemone-front

# 結果確認(新規バージョンファイルが見える必要があります。)
ls $INSTALL_DIR/bins/exemone-api
ls $INSTALL_DIR/bins/exemone-core

(7.1) coreサービスdbパスのコピー(core専用の特記事項)

他のサービスとは異なり、exemone-core は services/exemone-core/db パスを新規パッケージから既存インストールにそのまま持ってくる必要があります。(スキーマ/初期データ等)

# マイグレーションdbディレクトリバックアップ
mv $INSTALL_DIR/services/exemone-core/db $INSTALL_DIR/services/exemone-core/db_$(date +%Y%m%d)

# 新規dbパスコピー
cp -a $NEW_PKG/services/exemone-core/db $INSTALL_DIR/services/exemone-core/

# 確認
ls $INSTALL_DIR/services/exemone-core/db

(8) ログローテーション設定

postgresql, redis, cache, front, https のログローテーション/リテンションは、ホストの logrotation ツールで管理するため、初期設定を行います。

# ログ管理プロセス実行
$INSTALL_DIR/scripts/setup-logrotate.sh

(9) postgresql max_connections設定

postgresql起動時に max_connections=1000 で実行されるよう、スクリプトを変更します。

$INSTALL_DIR/services/exemone-postgresql/start.sh

別の方法として、postgresqlの設定を手動で変更することもできます。

# max_connections変更
$INSTALL_DIR/services/exemone-postgresql/data/postgresql.conf

max_connections = 1000 # 設定変更

設定変更後は、postgresqlを再起動します。

(10) postgresql dumpスクリプトの置き換え

postgresql dumpスクリプトを新規バージョンに置き換えます。

rm $INSTALL_DIR/services/exemone-postgresql/dump_export.sh
rm $INSTALL_DIR/services/exemone-postgresql/dump_import.sh

mv $NEW_PKG/services/exemone-postgresql/dump_export.sh $INSTALL_DIR/services/exemone-postgresql/
mv $NEW_PKG/services/exemone-postgresql/dump_import.sh $INSTALL_DIR/services/exemone-postgresql/

1-3. サービス起動

chown -R exemone:exemone $INSTALL_DIR

cd $INSTALL_DIR
./onectl restart all

# 検証
./onectl stat

注意事項および参考

.env, kafka.env, server.properties, http.conf 等は顧客カスタム値が含まれる場合があるため、必ず diff で差分を確認した後に置き換えるか、手動でマージしてください。
本パッチを進める前に、$INSTALL_DIR, $NEW_PKG 環境変数が正確に指定されているか確認してください。
今回のバージョンから onectl がシェルスクリプトからバイナリ実行ファイルに変更されるため、既存のスクリプト呼び出し方式と差異がないか確認してください。
サービスバイナリ置き換え時はcp -arn オプション(-n = 既存ファイル保持)を必ず使用する必要があり、これによりインフラバイナリ(kafka/postgresql/redis等)と旧バージョンのファイルが保持されます。
exemone-core の db ディレクトリは他のサービスとは異なり、新規パッケージのファイルを必ずコピーする必要があり、これによりスキーマ/初期データが正常に反映されます。
KAFKA_OPTS の MaxDirectMemorySize が3G → 6Gに引き上げられます。ホストのメモリリソースが十分か点検してください。
check-config.sh は起動後にKafka設定値を検証する補助ツールのため、起動直後の検証用途として活用できます。
exemone-front/dist と version.txt は、バックアップファイル名に既存バージョンを含めて(dist_$VERSION, version_$VERSION.txt)、後のロールバックを容易にします。

※ Repository内のテーブル変更事項の更新が必要です。

Binaryモードパッチ

変更事項​

共通事前準備​

新規パッケージファイルの配置​

新規パッケージの展開(バイナリモード)​

envファイル置き換え時の共通原則​

1. バイナリ(Binary)モード​

1-1. サービス停止​

1-2. ⭐ 今回のバージョン固有の作業(バイナリ)​

(1) onectl関連作業​

(2) scripts/フォルダの置き換え​

(3) Kafka server.propertiesの更新(顧客カスタム確認後に置き換え)​

(4) Nginx http.confの更新(顧客カスタム確認後に置き換え)​

参考)http.conf内の手動マージ時 — gzipブロックの追加位置と内容​

(5) Kafka設定確認スクリプトの配置(補助ツール)​

(6) .envの更新(手動マージ)​

(7) サービスバイナリの置き換え​

(7.1) coreサービスdbパスのコピー(core専用の特記事項)​

(8) ログローテーション設定​

(9) postgresql max_connections設定​

(10) postgresql dumpスクリプトの置き換え​

1-3. サービス起動​

注意事項および参考​