環境構築手順を追加

2026-09-06 20:28:09 +09:00
@@ -0,0 +1,393 @@
 # サーバー環境構築
 ## 概要
 このページでは、`nizika_ai_service` を Ubuntu 26.04 LTS 上で稼働させるための環境構築手順を記載する。
 本リポジトリは単独では完結せず、主に以下と連携する。
 - `nizika_ai`
 - `nizika_nico`
 - MySQL
 - OpenAI API
 本番環境では systemd により常駐させる。
 今回の構成例:
 ```text
 OS: Ubuntu 26.04 LTS
 Python: 3.14
 MySQL: 8.4 系
 /opt/nizika-ai-service
 /opt/nizika-nico
 ```
 ---
 # 1. セキュリティ方針
 サーバー侵害後の復旧や、新しいサーバーへの移行では、旧ホストから以下をそのままコピーしない。
 - API key
 - DB password
 - systemd unit
 - cron
 - hook
 - SSH private key
 - Python cache
 - 信頼できない実行ファイル
 - 秘密情報入り設定ファイル
 ソースコードは信頼できる Gitea の最新 `main` から取得する。
 DB password、OpenAI API key 等は新規発行する。
 アプリケーションから MySQL の `root` user は使用しない。
 ---
 # 2. service user
 専用 user を作成する。
 ```bash
 useradd --system \
  --home /var/lib/nizika-ai \
  --create-home \
  --shell /usr/sbin/nologin \
  nizika-ai
 ```
 確認:
 ```bash
 id nizika-ai
 ```
 ---
 # 3. repository
 Gitea から最新 `main` を取得し、
 ```text
 /opt/nizika-ai-service
 ```
 へ配置する。
 `nizika_nico` は、
 ```text
 /opt/nizika-nico
 ```
 へ配置する。
 旧サーバーの working tree をそのままコピーするのではなく、信頼できる Git repository から再取得する。
 ---
 # 4. Python package
 この環境では venv を使用せず、system Python を使用する。
 pip install 前に必ず:
 ```bash
 umask 022
 export HOME=/root
 ```
 を実行する。
 `umask 077` のまま pip install すると、
 ```text
 /usr/local/lib/python3.14/dist-packages
 ```
 配下が root のみ読み取り可能になり、service user から Python package が正常に import できなくなることがある。
 必要 package:
 ```bash
 python3 -m pip install \
  --break-system-packages \
  'eloquent==0.5' \
  'mysqlclient==2.2.8' \
  'openai==1.43.0' \
  'httpx[http2]==0.27.2' \
  'requests==2.32.5' \
  simplejson
 ```
 ## OpenAI / HTTPX
 この環境では:
 ```text
 openai==1.43.0
 httpx==0.27.2
 ```
 を使用する。
 OpenAI 1.43.0 は HTTPX 0.28 系と互換性問題があるため、HTTPX は 0.27.2 に固定する。
 ---
 # 5. Python package の権限確認
 service user から import できない場合:
 ```bash
 find /usr/local/lib/python3.14/dist-packages \
  -type d ! -perm -005 -o -type f ! -perm -004 \
  -print \
  | head -100
 ```
 過去に誤った `umask` で package が配置されていた場合:
 ```bash
 chmod -R a+rX \
  /usr/local/lib/python3.14/dist-packages
 ```
 ---
 # 6. MySQL
 `nizika_ai` DB 用に専用 user を作成する。
 例:
 ```sql
 CREATE USER 'nizika_ai_app'@'localhost'
 IDENTIFIED BY 'NEW_RANDOM_PASSWORD';
 GRANT ALL PRIVILEGES
 ON nizika_ai.*
 TO 'nizika_ai_app'@'localhost';
 ```
 `nizika_nico` DB についても別 user を使用する。
 例:
 ```sql
 CREATE USER 'nizika_nico_app'@'localhost'
 IDENTIFIED BY 'ANOTHER_NEW_RANDOM_PASSWORD';
 GRANT ALL PRIVILEGES
 ON nizika_nico.*
 TO 'nizika_nico_app'@'localhost';
 ```
 DB は信頼できる dump から復元する。
 確認:
 ```bash
 mysql -u nizika_ai_app -p \
  -e 'USE nizika_ai; SHOW TABLES;'
 mysql -u nizika_nico_app -p \
  -e 'USE nizika_nico; SHOW TABLES;'
 ```
 ---
 # 7. environment variable
 秘密情報は Git repository や systemd unit に直接書かない。
 以下を作成する。
 ```text
 /etc/nizika-ai-service.env
 ```
 内容:
 ```dotenv
 NIZIKA_AI_MYSQL_USER=...
 NIZIKA_AI_MYSQL_PASS=...
 NIZIKA_NICO_MYSQL_USER=...
 NIZIKA_NICO_MYSQL_PASS=...
 NIZIKA_NICO_DIR=/opt/nizika-nico
 OPENAI_API_KEY=...
 OPENAI_ORGANISATION=...
 ```
 権限:
 ```bash
 chown root:root /etc/nizika-ai-service.env
 chmod 600 /etc/nizika-ai-service.env
 ```
 ---
 # 8. OpenAI credential
 OpenAI credential は source code に直書きしない。
 例:
 ```python
 import os
 OPENAI_ORGANISATION: str = os.environ['OPENAI_ORGANISATION']
 OPENAI_API_KEY: str = os.environ['OPENAI_API_KEY']
 ```
 DB credential も environment variable から取得する。
 ---
 # 9. foreground test
 systemd 化する前に foreground で起動確認する。
 ```bash
 cd /opt/nizika-ai-service
 set -a
 . /etc/nizika-ai-service.env
 set +a
 runuser -u nizika-ai \
  --preserve-environment \
  -- \
  python3 /opt/nizika-ai-service/main.py
 ```
 正常に起動することを確認する。
 ---
 # 10. systemd
 以下を作成する。
 ```text
 /etc/systemd/system/nizika-ai-service.service
 ```
 内容:
 ```ini
 [Unit]
 Description=Nizika AI Service
 After=network-online.target mysql.service
 Wants=network-online.target mysql.service
 [Service]
 Type=simple
 User=nizika-ai
 Group=nizika-ai
 WorkingDirectory=/opt/nizika-ai-service
 EnvironmentFile=/etc/nizika-ai-service.env
 ExecStart=/usr/bin/python3 /opt/nizika-ai-service/main.py
 Restart=always
 RestartSec=2
 [Install]
 WantedBy=multi-user.target
 ```
 反映:
 ```bash
 systemctl daemon-reload
 systemctl enable \
  nizika-ai-service.service
 systemctl start \
  nizika-ai-service.service
 ```
 確認:
 ```bash
 systemctl --no-pager --full status \
  nizika-ai-service.service
 ```
 ログ:
 ```bash
 journalctl \
  -u nizika-ai-service.service \
  -n 100 \
  --no-pager
 ```
 ---
 # 11. reboot 後の自動起動
 確認:
 ```bash
 systemctl is-enabled \
  nizika-ai-service.service
 ```
 期待:
 ```text
 enabled
 ```
 再起動後:
 ```bash
 systemctl is-active \
  nizika-ai-service.service
 ```
 期待:
 ```text
 active
 ```
 ---
 # 12. 関連リポジトリ
 ## nizika_ai
 AI 関連の共通 code を提供する。
 DB credential と OpenAI credential は environment variable 経由で利用する。
 ## nizika_nico
 ニコニコ関連の共通処理や DB を利用する。
 パス:
 ```text
 /opt/nizika-nico
 ```
 environment variable:
 ```text
 NIZIKA_NICO_DIR=/opt/nizika-nico
 ```
 `nizika_ai_service` から `nizika_nico` 内の script が子プロセスとして起動される場合がある。