Blueskyの不具合対処法｜画像が黒くなる・投稿できない原因と解決方法

Blueskyで「画像が黒くなる」「プロフィール画像が更新できない」「画像付き投稿がうまくいかない」といった不具合が起きることがあります。

本記事では、実際にBlueskyの自己ホスト版PDSを運用中に発生した不具合をもとに、原因の切り分け方法と解決手順をまとめました。特に、画像投稿やプロフィール画像の更新が失敗する場合に確認したいポイントを紹介します。

セルフホスト環境でBlueskyを運用していて、画像関連の不具合で困っている方は参考にしてください。

Blueskyで起きた不具合の概要
まず確認した症状
今回の環境
Blueskyで画像投稿できない時の確認ポイント
エラーログから分かったこと
今回の原因は何だったのか
1. BLOB保存ディレクトリの参照先がずれていた
2. 環境変数の設定と実際のマウント先に不整合があった
実際に行った修正手順
修正後の動作確認
根本原因のまとめ
再発防止チェックリスト
セルフホスト運用で学んだこと
補足：生成AIで原因調査を進めた方法
よくある質問（FAQ）
まとめ

Blueskyで起きた不具合の概要

今回発生したのは、Blueskyの自己ホスト版PDSを運用中に起きた画像関連の不具合です。

具体的には、画像付き投稿を行うと画像が黒く表示される、プロフィール画像やヘッダー画像を更新しても反映されない、といった症状が発生しました。

一方で、テキスト投稿自体は正常に動作しており、PDSのヘルスチェックも 200 OK を返していました。そのため、PDS全体が停止しているのではなく、画像保存まわりに問題があると考えられました。

まず確認した症状

今回の不具合では、次のような症状を確認しました。

Bluesky Web から画像付き投稿を行うと、画像が真っ黒になる
プロフィール画像やヘッダー画像を変更しても反映されない
テキスト投稿は成功する
PDSは正常稼働しており、curl /xrpc/_health は 200 OK を返す

この時点で、PDS全体が停止しているわけではなく、画像関連の処理だけに問題がある可能性が高いと判断しました。

今回の環境

今回の不具合は、以下のようなセルフホスト環境で発生しました。

サーバー：Ubuntu 22.04 LTS
Docker で Bluesky PDS を運用
逆プロキシ：Caddy + Cloudflare
PDS イメージ：ghcr.io/bluesky-social/pds:0.4
データ永続化パス：/pds → コンテナ内 /app/data にマウント

Blueskyで画像投稿できない時の確認ポイント

Blueskyで画像付き投稿がうまくいかない場合は、まずPDSの保存先設定とディレクトリ権限を確認します。

特にセルフホスト環境では、PDS_DATA_DIRECTORY と PDS_BLOBSTORE_DISK_LOCATION の参照先がずれていると、画像が正しく保存されず、黒い画像になったり、プロフィール画像が更新できなかったりすることがあります。

また、Dockerのボリュームマウントが正しく設定されていない場合も、見かけ上はPDSが起動していても画像関連の処理だけ失敗することがあります。

まず確認したいポイントは次の5つです。

PDS_DATA_DIRECTORY の参照先
PDS_BLOBSTORE_DISK_LOCATION の参照先
BLOB保存ディレクトリの有無
ディレクトリ権限
Dockerのボリュームマウント設定

PDS_DATA_DIRECTORY の参照先を確認する

まず確認したいのは、PDS_DATA_DIRECTORY が実際の保存先ディレクトリと一致しているかどうかです。ここがずれていると、PDS本体が正しい保存先を認識できません。

PDS_BLOBSTORE_DISK_LOCATION の参照先を確認する

画像やプロフィール関連のデータは、BLOB保存先ディレクトリに格納されます。そのため、PDS_BLOBSTORE_DISK_LOCATION が正しい場所を指しているかどうかも重要です。

BLOB保存ディレクトリが存在するか確認する

ディレクトリ自体が存在しない場合、画像保存に失敗します。特にコンテナ再生成後は、保存先ディレクトリの再作成漏れが起きることがあります。

ディレクトリに書き込み権限があるか確認する

保存先が存在していても、書き込み権限が不足していれば正常に画像を保存できません。権限設定も必ず確認したいポイントです。

Dockerのボリュームマウント設定を確認する

PDSのコンテナ内パスとホスト側ディレクトリの対応がずれていると、表面的にはPDSが起動していても、画像保存だけが失敗することがあります。

エラーログから分かったこと

docker logs を確認したところ、以下のエラーが出ていました。

TypeError: Cannot open database because the directory does not exist

このエラーから、PDSがSQLiteデータベースを開けておらず、参照先ディレクトリの構造が壊れている、または存在しない可能性が高いと判断しました。

今回の原因は何だったのか

環境変数 /pds/pds.env を確認したところ、以下の設定になっていました。

PDS_DATA_DIRECTORY=/app/data
PDS_BLOBSTORE_DISK_LOCATION=/app/data/blocks

コンテナ再生成時にマウントパスがずれていたため、PDSが初期化エラーで終了していたことが原因でした。

つまり、画像そのものの不具合ではなく、BLOB保存ディレクトリの参照先不一致と永続化パスの不整合が本質的な問題でした。

BLOB保存ディレクトリの参照先がずれていた

PDSは画像ファイルを保存するために、正しいBLOBディレクトリを必要とします。今回のように参照先がずれていると、画像保存に失敗し、結果として画像が黒く表示されたり、プロフィール画像が更新できなくなったりします。

環境変数の設定と実際のマウント先に不整合があった

設定ファイル上では正しく見えていても、Docker側のマウントがずれていると、実際には保存先が存在しないのと同じ状態になります。セルフホスト環境では、このズレが不具合の原因になりやすいです。

実際に行った修正手順

ディレクトリを再作成して権限を修復する

まず、BLOB保存先ディレクトリを再作成し、必要な権限を付与しました。

mkdir -p /pds/blocks
chmod -R 777 /pds/blocks
docker restart pds

コンテナ内で保存先ディレクトリを確認する

次に、コンテナ内で /app/data/blocks が正しく見えているか確認しました。

docker exec -it pds sh -c 'ls -ld /app/data/blocks'

確認の結果、/app/data はホストの /pds に正しくマウントされており、blocks ディレクトリも認識されていました。

PDSを再起動して動作確認する

最後に、PDSを再起動し、ヘルスチェックと実際の投稿テストを行いました。

curl -I https://bluesky.j-makoto.online/xrpc/_health
HTTP/2 200 OK

修正後の動作確認

修正後は、プロフィール画像の再設定と画像付き投稿の両方が正常に反映されるようになりました。テキスト投稿だけでなく、画像関連の処理も問題なく動作することを確認できました。

根本原因のまとめ

問題点	原因	対応
画像が黒くなる	BLOBディレクトリ未マウント or 権限不足	/pds/blocks を再作成＋パーミッション調整
PDS起動時に TypeError	/app/data が存在しなかった	永続化ディレクトリを再確認
画像がアップロードできない	PDS_BLOBSTORE_DISK_LOCATION の参照先不一致	/app/data/blocks に統一