a-blog cms を動かすときのファイル・ディレクトリのパーミッションと所有権（owner / group）をまとめます。インストール時の権限エラー、メディアのアップロード失敗、オンラインアップデートの中断は、たいてい owner かパーミッションが原因で発生します。まずはここを確認してください。

基本は一律でこのパーミッション

ファイル・ディレクトリは、原則として全体を次の値にしておけば問題ありません。インストール・運用・アップデートで必要なパーミッションが変わることはなく、この一律の設定で足ります。

775 / 664 は、FTP ユーザーと PHP 実行ユーザーが別で、同一グループにまとめて運用する環境向けです。mod_php で PHP が www-data などの共通ユーザーで動くケースがこれにあたります。suEXEC や PHP-FPM のユーザー別プールのように、PHP がサイト所有者のアカウントで動くなら 755 / 644 で足ります。

パーミッションの数字よりも、owner と group が揃っているかのほうが効いてきます。owner が揃っていないと、パーミッションが正しくても書き込みや置換に失敗します。

本番で 777 にすると誰でも書き換えられるため、セキュリティ上避けてください。

なお archives/ media/ storage/ cache/ private/ は CMS が書き込みを行うディレクトリです。とはいえパーミッションは上の一律設定のままでよく、owner が PHP 実行ユーザーと合っていることが重要です。

PHP がどの OS ユーザーで動くか

推奨パーミッションが分かれる理由は、SAPI の種類ではなく PHP プロセスの実効 UID にあります。

SAPI 名から推測せず、実機で確認したほうが確実です。

<?php
echo posix_getpwuid(posix_geteuid())['name'], PHP_EOL; // 実効ユーザー名
echo php_sapi_name(), PHP_EOL;                          // fpm-fcgi, apache2handler 等
// posix 拡張が無ければ exec('whoami')

CMS が生成するファイルのパーミッション

アップロードやキャッシュ生成では、CMS 自身もファイル・ディレクトリを作成します。そのパーミッションは config.server.php の 定数で決まります。

既定はグループ書き込みあり（775 / 664 相当）が前提なので、上の一律設定と整合します。& ~umask() が掛かるため、実効パーミッションは PHP プロセスの umask 次第になります。意図したパーミッションにならないときは、 umask を確認してください。

所有権が重要

パーミッションよりも owner / group の一致のほうが、重要です。

いちばん堅いのは、CMS ファイル一式の owner を PHP 実行ユーザーに統一する方法です。これなら 755 / 644 で足ります。PHP 実行ユーザーと FTP ユーザーが別であれば、両者を同一グループに入れて group write（775 / 664）を付けてください。

よくある失敗が、FTP で上げたファイル（FTP ユーザー owner）と CMS が作ったファイル（PHP 実行ユーザー owner）が混ざり、ファイルごとに owner がばらばらになった状態です。これだとアップロードやアップデートで書き込みできなくなります。FTPでファイルを差し替えたら、owner とパーミッションを直してから運用・再アップデートしてください。直さずに再実行すると、同じ箇所で止まります。

POSIX 判定の順序に注意

POSIX のアクセス判定は owner → group → other の順で、最初に一致したクラスのビットだけを使います。後ろのクラスがいくら緩くても評価されません。

たとえばパーミッション 604（rw- --- r--、group ビットが 0）の場合は、次のようになります。

• owner なら read / write できます

• PHP 実行ユーザーが当該ファイルの group に属していると、group ビット --- で確定し、other に read があっても EACCES になります

• owner でも group でもない（other）なら read だけです

「other に read を付けたから大丈夫」のつもりでも、group が一致すると先に弾かれます。604 のような group ビットだけ 0 のパーミッションは避けてください。

困ったとき

オンラインアップデートで「書き込み権限がありません」と出て進まない。

アップデートはファイルを置換する前に、置換対象（php/ js/ themes/system/ など）とバックアップ先が書き込み可能かを事前チェックします。多くの権限問題はここで止まり、対象パスがメッセージに出ます。出ているパスの owner とパーミッションを直してからアップデートを再実行してください。

オンラインアップデートが途中で止まり、php/ や themes/system/ が消えた。

置換は旧ファイルを private/backup{YmdHis}/ に退避してから新ファイルを設置します。途中で失敗しても、通常は退避物から自動でロールバックされるため、消えたままにはなりません。問題になるのはロールバックできなかったときで、タイムアウトやメモリ不足でプロセスごと落ちると例外を捕捉できずロールバックが走りません（ロールバック自身も書き込めなければ途中で止まります）。その結果、退避物が private/backup{YmdHis}/ に残ったまま元の場所が空に見えます。退避物を確認し、owner とパーミッションを直してから戻してください。

メディアのアップロードや生成で 書き込みエラー。

archives/ media/ storage/ cache/ のどれかに、PHP 実行ユーザーから書き込みできていません。owner とパーミッションを確認してください。ディレクトリは実行権限も必要です。中のファイルへ辿るのに必要で、欠けていると読み取り・書き込み以前にアクセスできません。

パーミッションは正しいのに動かない。

表示上のパーミッションが合っていても、次の理由で 書き込みできないことがあります。

• umask — CMS が新規生成するファイル／ディレクトリの権限は (0775 & ~umask()) のように umask がデフォルトで適用されます。手で設定した値が正しくても、CMS が作るファイルだけ 書き込みできないなど、実効値が意図とずれることがあります。

• owner の不一致 — group / other に 書き込み権限を振っていない構成では、書けるのは owner だけです。親ディレクトリやファイルが別ユーザー所有だと、PHP 実行ユーザーが 書き込みできず rename や上書きに失敗します。chmod もファイル所有者しかできません。パーミッションの数字には owner が現れないので見落としがちです。

• open_basedir — PHP がアクセスできるパスを制限する設定です。OS のパーミッションが正しくても、範囲外のパスは PHP から触れません。

• SELinux / AppArmor — OS の通常パーミッションとは別の強制アクセス制御（MAC）レイヤーです。chmod / chown が正しくても、ポリシー側で拒否されることがあります。

コマンド例

実行前にバックアップを取り、<user> <group> は実環境の PHP 実行ユーザー／グループに置き換えてください。owner 変更には root 権限が必要で、共有ホスティングではホスティング側の対応が要る場合があります。

# owner を PHP 実行ユーザーに統一
chown -R <user>:<group> .

# 単一ユーザー環境: ディレクトリ 755 / ファイル 644
find . -type d -exec chmod 755 {} \;
find . -type f -exec chmod 644 {} \;

# 共有グループ環境: ディレクトリ 775 / ファイル 664
find . -type d -exec chmod 775 {} \;
find . -type f -exec chmod 664 {} \;

これまでインストーラーからインストールできるテーマは本体コードに直書きされており、制作者がオリジナルテーマをインストールできるテーマの選択肢に加えることはできませんでした。Ver. 3.2.27 より、コード改修なしに、ファイルを置くだけで選択肢を追加できるようになりました。標準の 5 テーマも、コアだからという特別扱いではなく、この仕組みに統一されています。

やること

setup/bin/<テーマ名>/ ディレクトリを作り、その中に次のファイルを置きます。本体の改修や DB への登録は不要です。

これに加えて、themes/<テーマ名>/ に実際のテンプレート本体も用意します。

setup/bin/my-theme/
├── theme.yaml       ← 宣言ファイル（必須）
├── my-theme.yaml    ← 流し込むサイトデータ（必須）
├── my-theme.png     ← サムネイル（任意）
├── media/           ← デモ用メディア（任意）
└── storage/         ← デモ用添付ファイル（任意）

themes/my-theme/     ← テンプレート本体

theme.yaml の書き方

既存の Blog テーマの宣言ファイル（setup/bin/blog/theme.yaml）を例にすると、次のような内容です。

key: blog
label: Blog
image: blog.png
order: 20
description: 時系列順のエントリー表示を前提にしたブログやニュースサイト向きのシンプルで機能的なテーマです。
comparison:
  カスタマイズ難易度: ★★
  デモデータ数: 1件
  テンプレートの継承: ○
  モジュールID利用: ×
  会員機能: ×
  コンテンツの表示切替: ×
  レイアウト機能: ×

各項目の意味は次のとおりです。

key は文字列として空でなければ何でもかまいませんが、label を欠く宣言は候補として成立しません（一覧に出ません）。key と label さえあれば選択肢として成立し、他の項目はすべて省略可能です。

マルチブログ（子ブログ）としてインストールする

オリジナルテーマのデモサイトを「メインブログ＋お知らせ用の子ブログ」のような複数ブログ構成でインストールしたい場合は、子ブログ用の bin を <子ブログ名>@<親 bin の名前> という名前で setup/bin/ 直下に並べて置きます。

setup/bin/
├── my-theme/                ← 親（ルートブログ）
│   ├── theme.yaml
│   ├── my-theme.yaml
│   └── ...
└── news@my-theme/           ← 子ブログ
    ├── news@my-theme.yaml   ← サイトデータ（ファイル名は必ず「<子 bin 名>.yaml」）
    └── config.yaml          ← 子ブログの名前・コード（任意）

親テーマ（この例では my-theme）がインストーラーで選ばれると、<子ブログ名>@my-theme というパターンに一致する bin が自動的に検出され、親ブログの子ブログとしてまとめてインストールされます。子ブログ用の bin に theme.yaml は不要です。テーマ選択肢の一覧には出さず、単体でも選べない（select_theme に直接指定しても拒否される）構成のため、宣言する必要がありません。

config.yaml（子ブログの名前・コード）

子ブログのブログ名・ブログコードは、子 bin 直下の config.yaml で指定します。

name: お知らせ
code: news

省略した場合は、bin 名の @ より前の部分（この例では news）がブログ名・ブログコードの両方にフォールバックします。

注意点

• 対応するのは 1 階層のみです。@ が 2 個以上含まれる bin（孫ブログにあたる構成）は検出対象外です。

• 子ブログの <子 bin 名>.yaml に書くデータは、親ブログとは別の blog_id に投入されます。テーブル内の blog_id は自分で確定させる必要はなく、インストール時に決まった子ブログの blog_id に自動的に書き換えられます。

仕組み・注意点

• 収集はインストーラー起動のたびに setup/bin/ 配下を走査するだけなので、ファイルを置けば即座に選択肢へ反映されます（管理画面や DB への事前登録は不要です）。

• 送信された選択値は、この宣言ファイルの一覧（許可リスト）と一致するものだけを受け付けます。宣言していない値（存在しないディレクトリ名など）を送っても拒否されます。

簡単セットアップで独自テーマを自動インストールする

a-blog cms が配布している「簡単セットアップ」スクリプトは、本体のダウンロード・展開・.htaccess 設定などをまとめて行う PHP ツールです。スクリプト冒頭の設定エリアに $theme_download_url / $theme_zip_file を指定しておくと、本体のセットアップと同時に、指定した独自テーマの ZIP も自動でダウンロード・展開・配置されます。制作者がオリジナルテーマを納品用に配布し、案件ごとに簡単セットアップだけでセットアップを終えたい場合などに使います。

// 特製テーマのインストール元を指定
$theme_download_url = "https://example.com/downloads/";
$theme_zip_file = "my-theme.zip";

配布 ZIP の作り方

配布する ZIP は、次の 2 つの形式のどちらでも作れます。どちらも拡張アプリ（プラグイン）を同梱できます。展開後の配置先は、テーマ本体が setup/bin/ と themes/、拡張アプリが extension/plugins/ です。

「bin / themes 直下」形式

ZIP のルート直下に bin/ themes/、必要なら plugins/ を並べて置く形式です。a-blog cms 本体の setup/bin/ themes/ 構成をそのまま ZIP 化したものにあたります。

（ZIP ルート）
├── bin/
│   └── my-theme/
│       ├── theme.yaml       ← インストーラーの選択肢として宣言
│       ├── my-theme.yaml
│       └── my-theme.png
├── themes/
│   └── my-theme/             ← テンプレート本体
└── plugins/                  ← 同梱したい拡張アプリ（任意）
    └── my-plugin/

展開後、bin/ は setup/bin/ へ、plugins/ は extension/plugins/ へそれぞれ移動され、config.server.php の HOOK_ENABLE が自動で 1 に設定されます。bin/<名前>/ に theme.yaml を同梱しておけば、この上の「theme.yaml の書き方」で説明した仕組みにそのまま乗り、インストール実行時にテーマ選択肢として表示されます。

「テーマ名ディレクトリ」形式

ZIP のルート直下にテーマ名のディレクトリを 1 つ置き、その中に bin/ themes/ plugins/ などをまとめる形式です。ディレクトリ名は ZIP ファイル名から決まります（拡張子と _ 以降を取り除いた部分。例: my-theme_1.0.zip → my-theme）。a-blogcms.jp が配布している既存テーマ（square@ec.zip など）はこの形式で配布されています。

（ZIP ルート）
└── my-theme/
    ├── bin/
    │   └── my-theme/
    │       ├── theme.yaml
    │       ├── my-theme.yaml
    │       └── my-theme.png
    ├── themes/
    │   └── my-theme/
    └── plugins/               ← 同梱したい拡張アプリ（任意）
        └── my-plugin/

挙動は「bin / themes 直下」形式と同じで、plugins/ を同梱すれば extension/plugins/ へ配置され HOOK_ENABLE が自動で 1 に設定されます。

注意点

• スクリプトはセットアップ開始前に、指定した URL が実際に到達可能か（HTTP ステータス 200 を返すか）を確認します。到達できない場合はエラー表示でセットアップが止まるため、配布 URL・ファイル名に誤りがないか事前に確認してください。

• GitHub Releases の releases/latest/download/... のようにリダイレクトを経由する URL も配布元として使えます（最終的なリダイレクト先のステータスで到達可否が判定されます）。