環境構築手順 を追加

%E7%92%B0%E5%A2%83%E6%A7%8B%E7%AF%89%E6%89%8B%E9%A0%86.md

@@ -0,0 +1,231 @@
+# サーバー環境構築
+
+## 概要
+
+`nizika_ai` はニジカ AI 関連の共通 code を提供する repository である。
+
+この repository 自体を独立した systemd service として起動するものではない。
+
+主に以下から利用される。
+
+- `nizika_ai_service`
+- `nizika_broadcast`
+
+---
+
+# 1. セキュリティ方針
+
+DB password、OpenAI API key 等の秘密情報を repository 内へ保存しない。
+
+旧サーバーから秘密情報入り設定ファイルをそのままコピーしない。
+
+アプリケーションから MySQL の `root` user は使用しない。
+
+---
+
+# 2. database
+
+`nizika_ai` DB への接続には専用 MySQL user を使用する。
+
+environment variable:
+
+```text
+NIZIKA_AI_MYSQL_USER
+NIZIKA_AI_MYSQL_PASS
+```
+
+例:
+
+```sql
+CREATE USER 'nizika_ai_app'@'localhost'
+IDENTIFIED BY 'NEW_RANDOM_PASSWORD';
+
+GRANT ALL PRIVILEGES
+ON nizika_ai.*
+TO 'nizika_ai_app'@'localhost';
+```
+
+---
+
+# 3. OpenAI credential
+
+OpenAI credential は environment variable から取得する。
+
+使用する variable:
+
+```text
+OPENAI_API_KEY
+OPENAI_ORGANISATION
+```
+
+例:
+
+```python
+import os
+
+OPENAI_ORGANISATION: str = os.environ['OPENAI_ORGANISATION']
+OPENAI_API_KEY: str = os.environ['OPENAI_API_KEY']
+```
+
+---
+
+# 4. Python environment
+
+本番では `nizika_ai_service` と同じ system Python を使用する。
+
+今回の環境:
+
+```text
+Ubuntu 26.04 LTS
+Python 3.14
+```
+
+主要 package:
+
+```text
+openai==1.43.0
+httpx==0.27.2
+eloquent==0.5
+mysqlclient==2.2.8
+requests==2.32.5
+simplejson
+```
+
+install 前:
+
+```bash
+umask 022
+```
+
+---
+
+# 5. HTTPX の version
+
+OpenAI Python library 1.43.0 と組み合わせる場合:
+
+```text
+httpx==0.27.2
+```
+
+を使用する。
+
+HTTPX 0.28 系では OpenAI 1.43.0 と互換性問題が発生する。
+
+---
+
+# 6. Python package permission
+
+system-wide pip を使う場合、`umask 077` のまま install しない。
+
+誤って root のみ読み取り可能になった場合:
+
+```bash
+chmod -R a+rX \
+  /usr/local/lib/python3.14/dist-packages
+```
+
+確認:
+
+```bash
+find /usr/local/lib/python3.14/dist-packages \
+  -type d ! -perm -005 -o -type f ! -perm -004 \
+  -print \
+  | head
+```
+
+---
+
+# 7. 利用側の environment file
+
+`nizika_ai_service` から利用する場合:
+
+```text
+/etc/nizika-ai-service.env
+```
+
+例:
+
+```dotenv
+NIZIKA_AI_MYSQL_USER=...
+NIZIKA_AI_MYSQL_PASS=...
+
+OPENAI_API_KEY=...
+OPENAI_ORGANISATION=...
+```
+
+`nizika_broadcast` から利用する場合:
+
+```text
+/etc/nizika-broadcast.env
+```
+
+例:
+
+```dotenv
+NIZIKA_AI_MYSQL_USER=...
+NIZIKA_AI_MYSQL_PASS=...
+```
+
+秘密値は Git に commit しない。
+
+---
+
+# 8. 動作確認
+
+利用する service user から import と DB 接続を確認する。
+
+秘密値そのものは標準出力へ表示しない。
+
+例:
+
+```bash
+python3 - <<'PY'
+import openai
+import httpx
+import eloquent
+import MySQLdb
+
+print("openai:", openai.__file__)
+print("httpx:", httpx.__file__)
+print("eloquent:", eloquent.__file__)
+print("MySQLdb:", MySQLdb.__file__)
+PY
+```
+
+---
+
+# 9. systemd
+
+`nizika_ai` 自体には独立した systemd unit を作成しない。
+
+常駐処理は:
+
+```text
+nizika-ai-service.service
+```
+
+が担当する。
+
+放送処理側では:
+
+```text
+nizika_broadcast.service
+```
+
+から利用される。
+
+---
+
+# 10. 関連リポジトリ
+
+## nizika_ai_service
+
+`nizika_ai` を利用して AI 常駐処理を行う。
+
+## nizika_broadcast
+
+放送処理から `nizika_ai` の DB や共通 code を利用する場合がある。
+
+## nizika_nico
+
+共通データやニコニコ関連処理として併用される。