# 05 想定される主要エラー時の対処

現場で発生しやすい主要なエラー／異常とその切り分け・復旧手順をまとめる。

---

## 作業担当者の区分について

各対処手順には以下の区分を記載する。

| 区分 | 意味 |
| --- | --- |
| **当社可** | 当社スタッフ（ほぼ素人）が実施してよい確認・軽微な復旧作業 |
| **要確認** | 実施前に山本さんへ確認してから進める作業 |
| **山本さん依頼** | 当社側での実施は不可。山本さんへ依頼する作業 |

**接続方法と実行ユーザーの基本:**

- サーバーへの接続: SSH で `skin` ユーザーとしてログイン（山本さんが設定した鍵認証）
- `pm2` コマンド: `skin` ユーザーで直接実行可能（`sudo` 不要）
- `sudo` が必要なコマンド: nginx の再起動・MySQL の操作・システム設定変更など

---

## 1. Web 画面が開かない（app.hada-check.com にアクセスできない）

### 1.1 症状別の確認と対処

| 症状 | 想定原因 | 区分 | 対処 |
| --- | --- | --- | --- |
| ブラウザで 502 Bad Gateway | PM2 の PHP プロセスが落ちている | **当社可** | `pm2 list` で `skin` を確認 → `pm2 restart skin` |
| ブラウザで 504 Gateway Timeout | PHP 処理が長時間返らない | **当社可** | 画像解析・PDF 生成を疑う。`pm2 logs skin` を確認 |
| ブラウザでつながらない（接続拒否・タイムアウト） | nginx が停止、または DNS・SSL 問題 | **当社可（確認のみ）** | 下記 1.2〜1.4 を参照 |
| 画面が真っ白 | PHP Fatal（`display_errors=0`） | **当社可** | `pm2 logs skin` を確認 |
| 500 系が連発 | PHP 側で例外 | **当社可** | 同上 |
| 「この接続はプライベートではありません」等SSL警告 | SSL 証明書の期限切れ | **要確認** | 証明書の更新（certbot renew）を山本さんへ確認 |

復旧の優先順位:

```bash
# [当社可] まず PHP 側を再起動
pm2 restart skin

# [要確認] 次に nginx（sudo が必要）
sudo systemctl restart nginx
```

### 1.2 nginx の確認

```bash
# [当社可] nginx の状態確認
sudo systemctl status nginx

# [当社可] nginx の設定テスト
sudo nginx -t

# [要確認] nginx の再起動
sudo systemctl restart nginx
```

### 1.3 DNS の確認

```bash
# [当社可] DNS が正しく設定されているか確認
nslookup app.hada-check.com
# または
dig app.hada-check.com
```

DNS の変更が必要な場合は ConoHa のコントロールパネルまたはドメイン管理業者で設定する。

### 1.4 SSL 証明書の確認

```bash
# [当社可] 証明書の有効期限確認
sudo certbot certificates

# [要確認] 証明書の更新（有効期限が近い場合）
sudo certbot renew
sudo systemctl reload nginx
```

SSL 証明書（Let's Encrypt）は通常 90 日で期限切れになる。Certbot が自動更新する設定になっているが、自動更新が失敗していた場合は手動で実施が必要。

### 1.5 443 / 80 ポートの確認

```bash
# [当社可] nginx がポートをリッスンしているか確認
sudo ss -tlnp | grep nginx
```

正常時: `443` と `80` に `nginx` が表示される。

---

## 2. DB に接続できない

症状: 画面に `Connect Error (xxxx) ...` が表示される。

切り分け:

```bash
# [要確認] MySQL の状態確認
sudo systemctl status mysql

# [要確認] MySQL への接続テスト
mysql -u admin -p -e "SHOW DATABASES;"
```

- MySQL が停止 → `sudo systemctl start mysql`（要確認）
- 認証エラー → `lib/environments/production.php` の `MYSQL_USER` / `MYSQL_PASSWORD` を確認（山本さん依頼）
- 特定クライアント DB だけ見えない → `c_{クライアント名}` DB の存在と権限を確認（山本さん依頼）

---

## 3. ログインできない（セッション関連）

症状: ログインしても `/client/login/` に跳ね返る / 認証後 `/client/` にアクセスすると無限ループ。

`pm2 logs skin` に `session_start(): open(/var/lib/php/sessions/sess_xxx) failed: Permission denied` が出ていたら、セッションファイルの所有者ズレが原因。

対処（要確認）:

```bash
sudo rm -f /var/lib/php/sessions/sess_*
sudo chown skin:skin /var/lib/php/sessions
sudo chmod 1733 /var/lib/php/sessions
```

ブラウザ側の `PHPSESSID` Cookie も削除（またはシークレットウィンドウで再ログイン）してから試す。

---

## 4. ZIP アップロードがエラーになる

画面に表示される主なメッセージと原因:

| メッセージ | 原因 |
| --- | --- |
| `zip内に、同じ名前のファイルが存在しています。` | ZIP 内のファイル名衝突 |
| `csv、jpg以外の拡張子のファイルが含まれています。` | ZIP 内に CSV / JPG 以外あり |
| `処理に失敗しました。(c004)` | CSV をワークディレクトリへ `rename` 失敗（権限／ディスク容量） |
| `処理に失敗しました。(b001)` | JPG の `rename` 失敗 |
| `処理に失敗しました。(b002)` | `convert` による 600×600 切り出し失敗 |
| `処理に失敗しました。(b003)` | `convert` による 300×300 切り出し失敗 |
| `処理に失敗しました。(b004)` | 画像解析エンジンの戻り値異常（7 値取れない／負値） |

対処:

1. [当社可] アップロードサイズ超過なら nginx `client_max_body_size` と PM2 起動コマンドの `-d upload_max_filesize / -d post_max_size` を増やす（要確認）。
2. [当社可] `files/uploaded_zip/` の残容量と書き込み権限を確認。
3. [当社可] `convert`（ImageMagick）がインストールされ、`/usr/local/bin/convert` にパスが通っていることを確認: `which convert`
4. `b004` が出た場合は [第 5 章 画像解析エンジンが動かない](#5-画像解析エンジンが動かない) を参照。

---

## 5. 画像解析エンジンが動かない

症状: `b004` が連発する／アップロード後に解析結果が得られない。

### 5.1 手動で動作確認

**区分: 当社可（手順通りに実施）**

`skin` ユーザーで SSH ログイン後、以下を実行する。

```bash
# test_input.jpg は 300x300 の JPG 画像を用意する（実際の診断で使用する Crop1 画像が理想）
# test_output.bmp はコマンド実行後に自動生成される出力ファイル（確認後に削除してよい）

WINEPREFIX=/home/skin/.wine-skindiagnosis xvfb-run -a wine \
  /home/skin/asp.hada-check.com/bin/SkinDiagnosisSystem/SkinDiagnosisSystem2.exe \
  /tmp/test_input.jpg /tmp/test_output.bmp
```

**`test_input.jpg` について:**
- サーバー内に別途用意した検証用の 300×300 JPG でも可
- より正確な動作確認には、実際の診断で生成された `files/uploaded_zip/.../KCheckerIng/Crop1/` 配下の JPG を使用することを推奨
- ImageMagick で生成した 300×300 のトゥルーカラー JPG であれば動作する

**`test_output.bmp` について:**
- コマンド実行後に自動生成される出力ファイル
- 確認後は削除してよい（`rm /tmp/test_output.bmp`）

期待値: 標準出力にカンマ区切りの 7 個の数値が表示される（例: `0.XXX,3XXX,0.XXX,1XXX,XXX,XX,0.0XXX`）。

### 5.2 切り分け観点

| 観点 | 確認コマンド | 正常時の例 | 区分 |
| --- | --- | --- | --- |
| Wine が入っているか | `wine --version` | `wine-6.0.3` などが表示 | **当社可** |
| Xvfb が入っているか | `which xvfb-run` | `/usr/bin/xvfb-run` が表示 | **当社可** |
| Wine プレフィックスが壊れていないか | `ls /home/skin/.wine-skindiagnosis/drive_c` | `Program Files`, `windows` 等が表示 | **当社可** |
| Wine プレフィックスの所有者 | `ls -la /home/skin/ \| grep .wine-skindiagnosis` | `skin skin` と表示 | **当社可** |
| 実行ファイルの存在と実行ビット | `ls -la /home/skin/asp.hada-check.com/bin/SkinDiagnosisSystem/` | `SkinDiagnosisSystem2.exe` に `x` ビット | **当社可** |
| 入力 JPG の形式 | `identify /tmp/test_input.jpg`（ImageMagick） | `300x300` で `JPEG`、`TrueColor` | **当社可** |

**異常だった場合の次のステップ:**

- Wine が入っていない → Wine のインストールが必要（**山本さん依頼**）
- Xvfb が入っていない → `sudo apt install xvfb` で解決できる可能性（**要確認**）
- Wine プレフィックスが壊れている → 5.3 の再初期化手順を検討（**要確認**）
- 所有者が `skin` でない → `sudo chown -R skin:skin /home/skin/.wine-skindiagnosis`（**要確認**）
- 実行ファイルが存在しない → バックアップから復元（**山本さん依頼**）
- 入力 JPG が 300×300 でない → ImageMagick の動作確認（**当社可**）

### 5.3 Wine プレフィックス再初期化手順（最終手段）

**区分: 要確認（山本さんへ事前確認してから実施）**

**退避すべきファイル（再初期化前に必ずバックアップを取る）:**
- `/home/skin/.wine-skindiagnosis/` 全体をバックアップ: `tar czf ~/wine-skindiagnosis-backup.tar.gz /home/skin/.wine-skindiagnosis/`

再初期化手順:

```bash
# 1. バックアップ
tar czf ~/wine-skindiagnosis-backup.tar.gz /home/skin/.wine-skindiagnosis/

# 2. Wine プレフィックス削除・再初期化
rm -rf /home/skin/.wine-skindiagnosis
WINEPREFIX=/home/skin/.wine-skindiagnosis wineboot -u

# 3. 所有者修正
chown -R skin:skin /home/skin/.wine-skindiagnosis
```

**再初期化後に戻すファイル:**
- 通常は Wine プレフィックスの再初期化だけで動作が回復する
- `SkinDiagnosisSystem2.exe` は `/home/skin/asp.hada-check.com/bin/SkinDiagnosisSystem/` に置いてあるため Wine プレフィックスに戻す必要はない

**動作確認手順:**
1. 5.1 の手動確認コマンドを実行
2. 標準出力に 7 値が返れば成功

**注意:** 再初期化してもエラーが解消しない場合は、**株式会社テクノホライズン**または**山本さん**に相談すること。

---

## 6. PDF が生成できない／ダウンロードできない

**PDF 生成に失敗する場合と、生成済み PDF をダウンロードできない場合は原因が異なる。**

### 6.1 PDF 生成に失敗する場合

症状: 「PDF 作成」ボタンを押しても PDF が作られない、エラーが表示される。

| 確認箇所 | 確認コマンド / 方法 | 区分 |
| --- | --- | --- |
| PHP エラーログ | `pm2 logs skin --lines 100` | **当社可** |
| `files/pdf_result/` のディスク容量 | `df -h` | **当社可** |
| `files/pdf_result/` の書き込み権限 | `ls -la /home/skin/asp.hada-check.com/files/` | **当社可** |
| DB 上の診断結果の存在 | 管理画面から該当クライアントの結果一覧を確認 | **当社可** |
| user/ 配下のテンプレート画像 | 特定クライアントだけ失敗する場合は `user/{クライアント名}/images/pdf/` を確認 | **当社可** |

特定クライアントだけ PDF 生成が失敗する場合は、そのクライアントの `user/{クライアント名}/images/pdf/` のテンプレート画像が欠損している可能性がある。

### 6.2 生成済み PDF をダウンロードできない場合

症状: PDF の生成は完了しているが、ダウンロードリンクを押してもエラーになる。

| 確認箇所 | 確認コマンド / 方法 | 区分 |
| --- | --- | --- |
| PDF ファイルの存在確認 | `ls files/pdf_result/client_{id}_file_{file_id}/` | **当社可** |
| nginx アクセスログ | `tail -50 /var/log/nginx/access.log` | **当社可** |
| PHP エラーログ | `pm2 logs skin --lines 100` | **当社可** |

```bash
# PDF ファイルの存在確認例
ls /home/skin/asp.hada-check.com/files/pdf_result/client_10_file_3342/
```

### 6.3 文字化けする場合

| 症状 | 対処 | 区分 |
| --- | --- | --- |
| PDF の文字が文字化け | Smarty キャッシュを削除して再実行: `rm -rf Smarty/templates_c/* Smarty/cache/*` | **当社可** |
| 依然として文字化け | `lib/fpdf/mbfpdf.php` の動作確認が必要（**山本さん依頼**） | **山本さん依頼** |

---

## 7. テンプレートを修正したのに反映されない

原因: Smarty のコンパイルキャッシュが古い。

**区分: 当社可**

```bash
rm -rf /home/skin/asp.hada-check.com/Smarty/templates_c/*
rm -rf /home/skin/asp.hada-check.com/Smarty/cache/*
```

削除後は自動で再生成されるため、nginx / PM2 の再起動は不要。

---

## 8. ディスク容量不足

**区分: 当社可（確認のみ）、削除前に要確認**

```bash
# [当社可] ディスク使用量の確認
df -h

# [当社可] filesディレクトリ別の容量確認
du -sh /home/skin/asp.hada-check.com/files/*
```

| フォルダー | 削除可否 | 削除前のバックアップ | 注意 |
| --- | --- | --- | --- |
| `files/uploaded_zip/` 内の古いフォルダー | **削除可** | 不要（DB に結果保存済みなら中間ファイルは復元不要） | 日時が十分に古いものに限る。最新のものは削除しない |
| `files/pdf_result/` | **削除不可** | — | 再生成は可能だが診断結果の実体ファイル |
| `Smarty/templates_c/` | **削除可** | 不要（自動再生成） | — |
| `Smarty/cache/` | **削除可** | 不要（自動再生成） | — |
| `/var/log/nginx/` のログ | **削除可（ローテーション後）** | 要確認 | 古いログファイル（`.gz`）は削除可 |
| `/home/skin/.pm2/logs/` | **削除可** | 不要 | 古いログのみ。直近のログは確認用に残す |
| `user/` 配下 | **削除不可** | — | クライアント別テンプレート・画像（再生成不可） |
| `bin/SkinDiagnosisSystem/` | **削除不可** | — | 画像解析エンジン本体 |

古い `uploaded_zip/` フォルダーを削除する場合は、DB に診断結果が正常に保存されていることを管理画面で確認してから実施すること。

---

## 9. ログの場所

| 用途 | パス / コマンド |
| --- | --- |
| PHP（アプリ）エラー | `pm2 logs skin` / `/home/skin/.pm2/logs/skin-error.log` |
| PHP（アプリ）標準出力 | `/home/skin/.pm2/logs/skin-out.log` |
| nginx エラー | `/var/log/nginx/error.log` |
| nginx アクセス | `/var/log/nginx/access.log` |
| MySQL エラー | `/var/log/mysql/error.log` |
| システムログ | `/var/log/syslog` |

画面側でエラーコードが出たらまず `pm2 logs skin --lines 100` で PHP 側を確認する。

---

## 10. 問い合わせ経路

| 事象 | 相談先 |
| --- | --- |
| 画像解析エンジンの挙動・係数（`weightingfactor.ini`） | **株式会社テクノホライズン**（エンジン提供元） |
| Web 画面の不具合・サーバー全体の停止・OS 障害 | **山本さん**（保守担当。契約内容は別途協議） |
| サーバーのハードウェア・VPS 関連 | **ConoHa**（VPS 提供元） |

**山本さんへ相談する前に確認しておくこと:**
1. 症状（どの画面で、どんなエラーが出るか）
2. `pm2 logs skin --lines 100` の出力内容
3. 発生した日時
4. 直前に行った操作（コード変更・設定変更・ファイルアップロード等）

**注意:** 山本さんとの保守契約については、別途協議の上で決定する前提とする。