環境構築手順を追加

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 が子プロセスとして起動される場合がある。