4. 構築過程で発見・対処した問題
8件すべて、実際に動かして判明した内容
- .htpasswd が公開ルート直下に置かれ、.htaccess は全行コメントアウト（旧サイトの重大な設定不備）
- 管理画面でカスタムフィールドが編集できない（supports に custom-fields 欠落）
- 中身のない年度18本もリンク表示され、空ページへ飛ぶ状態
- 年度アーカイブが機能せず、ブログ形式・投稿日で表示
- 一括投入で画像圧縮が効かない経路があり、原本1.71MBが残る
- 静的アーカイブが全ページ文字化け（HTTPヘッダのcharsetがmetaより優先）
- マニュアルの開催日入力手順が実際の画面と相違（手順どおりに操作すると失敗する）
- 空の画像ブロック20個がすべて検証エラー
5. 旧サイト由来の誤記（原本どおり投入・訂正待ち）
| 行事名が空 | 2件 | 旧サイトが行事名自体をPDFリンクにしていた |
| 日付の年が1年ずれ | 3件 | 2008年度、曜日は正しく年だけ誤り |
| 曜日が合わない | 4件 | 2020〜2023年度 |
| 表記の重複誤記 | 3件 | 「先進企業視察会視察会」 |
| 名簿の疑わしい記載 | 6件 | 「幹事→監事」「㈱ダイクレ㈱」等 |
6. 事務局向けマニュアル
780行・9章＋付録2
対象を事務局に絞り、管理者向けの内容とは分けた・・・マニュアルは公開サイト上の固定ページとして設置している・・・更新経路は「ページ上で直接編集」に一本化・・・ 変換スクリプトとページ編集の二経路があると、どちらかの修正が失われる・・・スクリプトは移行用の一度きりのものとして明記のうえ保管
1. 移行前の状態と課題
| 構成 | frameset ベースの静的HTML |
| 規模 | 773ファイル / 2.74GB |
| 制作 | Dreamweaverで約15年間 |
| スマホ対応 | なし |
2. 資産の棚卸し
破棄したもの
| 運営委員会PDF | 1,534本 / 206MB | パスワード運用ごと廃止 |
| 死蔵HTML | 654本 | トップから到達不能な滞留分 |
| 制作元データ（.mif / .pef） | 207MB | サイト運用に不要 |
移行したもの
| 行事 | 192件（2008〜2025年度・18年分） |
| 添付ファイル | 368件 / 84MB（写真138・PDF230） |
| 固定ページ | 8本（協会案内5・名簿2・マニュアル1） |
| 静的アーカイブ | 16本（1992〜2007年度） |
3. 設計の要点
3-1. データと見た目の分離
| 親テーマ | twentytwentyfive（WordPress公式） | 本体と同時に更新される基盤 |
| 子テーマ | qmac（新規作成） | 配色・レイアウト・動的ブロック |
| プラグイン | qmac-core（新規作成） | 投稿タイプ・分類・管理画面整理 |
3-2. ブロックテーマの子テーマ方式を採用
当初はクラシックテーマを検討したが撤回した・・・クラシックテーマはWordPress本体の更新に追従しにくく、ブロックエディタで書かれた投稿との整合が崩れやすい・・子テーマ方式なら親テーマが本体と一緒に更新され、独自の差分だけを自前で保守すればよい。保守性と自由度が両立する・・・・親テーマが公式テーマである点も重要で、コアチームが保守しており、第三者テーマのように開発停止で行き詰まるリスクが小さい
3-3. 事務局が壊せる箇所を構造的に減らした
「マニュアルに書いてあるから大丈夫」ではなく、そもそも触れないようにする方針
| 権限 | 編集者権限（外観・プラグイン・ツールに到達不可） |
| 左メニュー | 5項目に限定 |
| ブロック | 102種を非表示にし、17種のみ許可 |
| パターン | 挿入可能なパターンを0本に |
| テンプレート | 編集欄を非表示にしたうえ、保存自体を拒否 |
3-4. 年度アーカイブの自動化
現行運用で最も手間だった作業を自動化・・・開催日を入力するだけで、年度タームの作成・付与・サイドパネルへの反映がすべて自動で行われる・・事務局の手作業はゼロ・・・・年度末の切替も、状態を「予定 → 終了」に変えるボタン1つ（取り消し可）に集約
| 更新の担い手 | 事務局 |
| 行事の追加 | 管理画面で入力 |
| 年度末の切替 | ボタンで切り替え |
| 過去年度リンク | 完全自動 |
| 写真の掲載 | ドラッグで追加（自動圧縮） |
| スマホ対応 | あり |
WordPress化したサイトのXserverへのデプロイ
1. 計画変更を要した前提の齟齬
1-1. qmac.jp を協会アカウントに追加できない
「既に設定されています」というエラーで追加不可・・・同一ドメインを2つのXserverアカウントに同時設定することはできないため、旧サイトが稼働している限り新アカウントに追加できない
影響： 「新旧を並行稼働させ、DNSを向け替えるだけの無停止移行」という当初方式が使えなくなった・・・切替は「旧アカウントから削除 → 新アカウントに追加」となり、1〜3時間の停止が発生する。
1-2. 初期ドメインにWordPressを設置できない
協会アカウントの初期ドメイン（xs815766.xsrv.jp）はWordPress簡単インストールの対象外で、サブドメインも作成できなかった。
対処： 検証専用の独自ドメイン(qmac.world)を新規取得し、これを構築・検証環境とした
- 事務局がリモートで実物に触れる（本番切替前に問題を出せる）
- SSLが即座に有効化でき、本番と同条件で検証できる
- 移行完了後も、WordPress本体のメジャー更新を本番に当てる前の試験環境として使える
2. 環境の事前確認で潰した地雷
| 項目 | ローカル | Xserver | 判定・対処 |
| WordPress | 7.1 | 7.1 | 一致 |
| テーブル接頭辞 | wp_ | wp_ | 一致（不一致なら投入直後に白画面） |
| DB照合順序 | utf8mb4_unicode_520_ci | 既定 general_ci | ダンプのテーブル定義が優先。対処不要 |
| MariaDB | 10.11.11 | 10.11.18 | 互換 |
| PHP（Web） | 8.4.16 | 8.3.33 | 問題なし |
| PHP（wp-cli） | — | 8.0.30 | 要対処 |
★ wp-cli のPHPバージョン問題
サイトは8.3.33で動くが、/usr/bin/wpは8.0.30で起動していた。wp search-replaceは内部でWordPressとプラグインを読み込むため、qmac-core に8.1以降の構文があれば置換の途中で落ち、DBが中途半端に書き換わる・・・・/usr/bin/php8.3が存在したため、これを明示して実行することで解決
bash
/usr/bin/php8.3 /usr/bin/wp
エイリアス登録は避けた。 一度、存在しないパスをエイリアスに書いてしまい、次回ログイン時に wpが全滅する状態を作りかけた・・・以後は毎回フルパスで実行する方式に統一
3.実行前の防御
破壊的操作の前に、戻せる状態を作成
| 対策 | 内容 |
| DBバックアップ | backup_before_migration_20260909.sql |
| ファイルバックアップ | wp-content_before_migration.tar.gz（20.7MB） |
| 設定ファイル退避 | .htaccess.orig/wp-config.php.orig |
| 検索エンジン除け | blog_public = 0 |
| アクセス遮断 | Basic認証（実在ドメインのため必須） |
| キャッシュ | Xアクセラレータを無効化 |
blog_public = 0 は「クロールしないでください」という要請にすぎず強制力がない・・実際の防御はBasic認証だけである点を作業中も繰り返し確認した・・・・Xアクセラレータの無効化は、DB入替後も古いページが表示され続けて「移設が失敗した」と誤判断することを防ぐため
4. 実行手順と要点
4-1. 転送（5本のアーカイブ）
| ファイル | サイズ | 内容 |
| qmac_wp_20260909.sql | 1.1MB | DBダンプ（12テーブル） |
| themes.zip | 8.0MB | qmac + twentytwentyfive |
| plugins.zip | 37KB | qmac-core |
| languages.zip | 1.4MB | 日本語翻訳 |
| uploads.zip | 108MB | 1,020ファイル |
md5を5本すべて照合してから展開。転送破損を後段で発見する事態を避けた・・・未使用テーマ3本（twentytwentytwo / three / four）は除外・・容量削減（22MB→8MB）より、更新通知・脆弱性の対象を減らす目的が大きい。事務局に渡すサイトに不要物を持ち込まない方針を通した
4-2. ★ db resetを db cleanに変更（重要な判断）
当初指示していた wp db resetは DROP DATABASE → CREATE DATABASE を実行する・・共有サーバではDBユーザに CREATE DATABASE権限がない場合があり、DBを削除した直後に再作成で失敗すると復旧が困難になる・・・wp db clean はDB自体を残してテーブルのみ削除するため、この事故が起こり得ない・・実行前に差し替えた
4-3. ★ URL置換件数の事前算出
http://qmac.test → https://qmac.world の置換にあたり、実行前にDBを直接集計して期待値を算出
- wp_options.option_value 2件
- wp_posts.post_content 12件
- wp_posts.guid 625件
- wp_users.user_url 1件
- 合計 640件
ダンプ内の文字列出現「箇所」数は648だが、wp search-replaceが報告するのは「レコード×カラム数」であるため、期待値は648ではなく640となる。この差を事前に把握していなければ、正常な結果を異常と誤判断していた・・・–dry-run の結果は 640・内訳も4カラムすべて予測と完全一致・・想定外のテーブルへの波及もゼロ・・この一致を確認したうえで本実行を承認した・・期待値を持たない検証は検証ではない・・出てきた数字が正しいかどうかを判断できないからである
4-4. 文字化け対策の予防的適用
ローカル構築時に静的アーカイブが文字化けした既知の問題（HTTPヘッダのcharsetがmetaより優先される）に対し、移設時点で予防措置を入れた
wp-content/uploads/qmac-archive/.htaccess
AddDefaultCharset UTF-8
結果、39本すべてで 実ファイル・meta・HTTPヘッダの三者がUTF-8で一致。再発なし
4-5. .htaccessの保全
wp rewrite flush –hard は .htaccess を書き換える・・ここにBasic認証4行が入っているため、消えれば検証サイトが公開状態になる・・・結果的にwp-cliが書き込みをスキップし、md5・mtimeとも不変だった・・flush前後と .orig の3点でmd5を照合して確認
5.検証結果
| 区分 | 本数 | ステータス | Content-Type | PHPエラー |
| トップページ | 1 | 200 | charset=UTF-8 | なし |
| 年度アーカイブ | 20 | 200 | charset=UTF-8 | なし |
| 固定ページ | 8 | 200 | charset=UTF-8 | なし |
| event投稿（抽出） | 5 | 200 | charset=UTF-8 | なし |
| 静的アーカイブ | 39 | 200 | charset=UTF-8 | なし |
| /wp-login.php | 1 | 200 | charset=UTF-8 | なし |
| 合計 | 74 | 全件200 | – | 0件 |
ステータス200だけでは不十分なため、全74本の本文を Fatal error / Warning: / Notice: / Parse error / Deprecated: で走査し、全件ヒットなしを確認した・・・PHPエラーが出ていても200が返る場合があるためである・・・あわせてトップページに行事タイトルが実際に描画されていることを確認し、テーマとプラグインが機能していることを裏づけた・・Basic認証はサーバ内・外部の双方から401を確認・・・検証URLはDBから自動抽出して組み立てた。手書きのリストでは実在しないURLを検証したり、実在するのに漏れたりする・・実際、想定18本の年度アーカイブは20本、想定12本の静的アーカイブは39本存在した（後者は「サイドパネルからリンクされている本数」と「実ファイル数」を混同していたもの）
6.資格情報の取り扱い
Basic認証のパスワードは、コマンドライン・チャット・ログのいずれにも残さない方式を採った・・・サーバ上に ~/.netrc（chmod 600）を作成し、curl –netrc で参照・・・ファイルの内容は表示・記録しない・・・検証完了後に削除。コマンドラインに直接書くと、シェル履歴とプロセス一覧の双方に平文で残る・・共有サーバでは特に避けるべき経路
7.現況と残作業
7-1. 完了
| 項目 | 状態 |
| 検証環境 https://qmac.world | 稼働（Basic認証・検索エンジン非公開） |
| データ | 行事200件・添付382件・固定ページ8本 |
| ファイル | uploads 1,020ファイル / 123MB |
| 動作確認 | 74URL全件200・PHPエラー0件・目視確認済 |
| ロールバック資材 | DB・wp-content とも保持 |
7-2. 残作業
- 目視確認で挙がった修正・・・ TAM
- 2旧サイト由来の誤記18件の訂正・・・ TAM（要事実確認）
- マニュアルへの画像貼り付け20点・・・ TAM
- 編集者アカウントでの動作確認・・・ TAM
- 事務局による確認・・・ 事務局
- qmac.jp への切替・・・TAM
以降のコンテンツ修正はすべてqmac.world側で行う。 ローカル環境は参照専用とし、二重管理を避ける
7-3. ★ 本番切替時の最重要事項
旧アカウントから qmac.jp を削除すると、DNSゾーン（MXレコードを含む）が消える・・・協会のメールはXserver外で運用しているため、新アカウントに追加した際にXserverの既定値でゾーンが再作成されると、MXがXserverを向き、メールが届かなくなる
切替手順の要点：
- 削除前に旧アカウントのDNSレコードを全項目記録（A / MX / TXT(SPF) / CNAME）
- 旧サイト一式をバックアップ（切り戻し用）
- 旧アカウントから qmac.jp を削除 ← ここから停止
- 協会アカウントに追加
- 最優先でMXレコードを元の値に再登録
- SSL発行 → サイト移設・URL置換
- 表示確認 → テストメール送受信
- 検索エンジン非公開の解除・Basic認証の解除
- サイトの表示より先にメールを復旧する順序を守る。所要1〜3時間を見込み、事務局への事前通知のうえ週末等に実施する