VS Code Server（~/.vscode-server）をコンテナごとのボリュームに重ねて持ち、更新のたびに旧版が溜まる #463

何を見つけたか

devbase_vscode_{project}_{index} はコンテナ 1 つに 1 本で、VS Code Server の本体（bin/<commit>）を各ボリュームが別々に持つ。VS Code の更新のたびに新しい版が入り、古い版が残るため、ボリュームが溜まっていく。

手元の端末で測った値（2026-10-12）:

コンテナごとに分けているのは、VS Code Server が「1 マシン 1 セット」の状態（data/Machine/.connection-token-<commit> など）を持ち、同時に書くと接続トークンを奪い合うためとされている（docs/user/container-operations.md の「VS Code Server の永続化」）。この奪い合いを実機で確かめた記録は無い。版ごとに中身が変わらない bin/<commit> には、この理由はそもそも当たらない。

案

~/.vscode-server を丸ごと全コンテナ共通の 1 本のボリュームにする。共有して困る理由として挙げてきた「接続トークンの奪い合い」が実際に起きるかは確かめていない（下の 7〜10）。問題が出た部分だけをコンテナごとに戻す。戻す順は data/ → extensions/ で、bin/ は最後まで共有する。

実機で確かめること

1. 2 つのコンテナで初めて同時に attach し、同じ版の bin/<commit> を同時にダウンロード・展開しても壊れないか（片方が展開途中の版を使わないか）
2. VS Code Server が使わなくなった古い版を bin/ から消すとき、別のコンテナが使っている版まで消さないか
3. 既存の devbase_vscode_* からの移り方（既存の bin/・extensions/ を共通のボリュームへ寄せるか、捨てて取り直すか）
4. 2 つのコンテナで拡張のインストール・更新・アンインストールが同時に起きたとき、extensions/extensions.json が壊れたり片方の書き込みが失われたりしないか
5. 拡張の自動更新が旧版に .obsolete の印を付けて消すとき、別のコンテナがまだ読み込んでいる旧版まで消さないか
6. サーバーの版が違うコンテナ同士（片方だけ VS Code を更新した状態）で同じ extensions/ を使えるか（拡張は対応するエンジンの版で入る版が変わる）
7. 接続トークン data/Machine/.connection-token-<commit>: 既にあれば読み、無ければ作る作りか。2 つのコンテナで初めて同時に起動したとき、両方が書いて後勝ちになり、先に起動した側の接続が切れるか（今の文書の「奪い合う」が実際に起きるか）
8. data/User/globalStorage・data/User/workspaceStorage の state.vscdb（SQLite）を複数のサーバーが同時に開いたとき、ロックの待ちや書き込みの失敗が出ないか
9. data/logs/ が起動ごとに別のディレクトリになり、ぶつからないか
10. data/Machine/settings.json をコンテナ間で同じにして困る設定が devbase の使い方にあるか

どこで見つけたか

スプリント m8a（#368 の受け入れ条件 9 の確認）で、ホストのディスクが満杯になった後に空きを作る作業で docker system df -v を見たとき。このときは各ボリュームの bin/ の旧版・extensionsCache/・extensions.json に無い拡張の旧版を手で消し、約 40GB から約 12GB にした。

なぜこの変更の範囲外なのか

スプリント m8a の課題（#455 #368）はスナップショットの除外と補完のテストで、VS Code Server のボリュームの構成を含まない。devbase_vscode_* はスナップショットの対象外でもある。

確かめた範囲で減る量の見込み

今回の手元では、bin/ の旧版が約 21GB、拡張の旧版の重複と extensionsCache/ で数 GB。丸ごと共有すると、同じ版をプロジェクトとインスタンスの数だけ重ねて持つことが無くなり、合計は 1 本分（今回の最大のボリュームで約 2GB）に近づく。拡張を一度入れれば全コンテナで使える。

直さないと何が起きるか

VS Code の更新のたびに、各ボリュームへ 1 版（約 0.6GB）ずつ溜まり続ける。プロジェクトとインスタンスの数だけ同じ版を重ねて持つため、ホストのディスクを圧迫する。手で消さない限り減らない。

由来

スプリント m8a の作業中の利用者との会話（2026-10-12）

依頼（原文）

#463。人へ問わずに進め、決められない点は前提か未決として課題の本文へ書く。（中略）課題の「案」（~/.vscode-server を丸ごと全コンテナ共通の 1 本にし、問題が出た部分だけコンテナごとに戻す。戻す順は data → extensions、bin は最後まで共有）を出発点にする。利用者の見立ては「data も事実上問題ない」。共有の単位（全体で 1 本か、グループごとか）、既存の devbase_vscode_* からの移り方と後片付け、コンテナの entrypoint（containers/base/entrypoint.sh の devbase_setup_vscode_server_dir）・lib/devbase/volume/compose.py・manager.py の変更、文書（docs/user/container-operations.md の「VS Code Server の永続化」）を決める。課題の「実機で確かめること」10 項目は、項目ごとに確かめ方を決める。（中略）実の VS Code からの attach が要る項目は、マージ前の手動確認として利用者か conductor へ回すと書く。

（書き手: AI の起動指示、日付: 2026-10-13。中略した部分は作業の制約（ボリュームを写さない・devbase up を打たない・base を建て直さない）で、要求の中身を含まない）

data も事実上問題ない

（書き手: 利用者（上の起動指示が引いた見立て）、日付: 不明。2026-10-12〜13 の会話と推す）

~/.vscode-server を丸ごと全コンテナ共通の 1 本のボリュームにする。（中略）問題が出た部分だけをコンテナごとに戻す。戻す順は data/ → extensions/ で、bin/ は最後まで共有する。

（書き手: 起票者（この課題の「案」の節）、日付: 2026-10-12。利用者の指示の原文としては扱わない）

(a) data/ はボリュームにせず、コンテナの書き込みレイヤーに残す。コンテナごとの VS Code Server の状態のボリューム（devbase_vscode-data_*）は作らない。(b) 共有するのは bin/ だけ。共通の VS Code Server ボリューム 1 本を ~/.vscode-server/bin に付ける。extensions/・extensionsCache/・data/ はコンテナの書き込みレイヤーに残り、devbase up の作り直し（down → up）で消える。docker restart・端末の再起動では消えない。

（書き手: 利用者の決定（承認ゲート 1）を伝えた conductor の起動指示、日付: 2026-10-14。失うものを conductor が動いているコンテナ 2 つで測り、利用者がそれを見て受け入れた。測った値は前提 7）

起票者の推定

目的

• VS Code Server の本体を、プロジェクトとインスタンスの数だけ重ねて持たず、全コンテナで 1 組にする
• VS Code の更新のたびに本体の旧版が溜まり続けることを止め、手で消さなくてもホストのディスクを使う量に上限がある状態にする
• 窓のタイトル・接続の再開は、今と同じくコンテナごとに分かれたまま働く

前提

• 前提 1（共有の範囲）: 共有するのは ~/.vscode-server/bin だけで、共通の VS Code Server ボリューム 1 本を ~/.vscode-server/bin に付ける。extensions/・extensionsCache/・data/ とその他の直下の置き場はどのボリュームにも置かず、コンテナの書き込みレイヤーに残る。docker restart と端末の再起動では残り、devbase up の作り直し（down → up）で消える。利用者が承認ゲート 1（2026-10-14）で決めた。bin/・extensions/・extensionsCache/ を共通のボリュームに置き、data/ はコンテナごとのボリュームに置く（2026-10-13 の版。data/Machine を共有すると .devport と window.title が後勝ちになることは「実機で確かめることの扱い」の 7・10 で確かめたが、data/ を書き込みレイヤーに残せばコンテナごとに分かれるため当たらない）
• 前提 2（共有の単位）: 共通の VS Code Server ボリュームは端末に 1 本で、アカウントグループで分けない。置くのはサーバーの本体だけで、認証の情報・拡張・拡張の保存する状態を持たない
• 前提 3（移り方）: 旧形式の VS Code Server ボリュームの中身は、新しいボリュームへ写さない。本体は最初の attach で取り直す（約 215MB、約 55 秒）。extensions/ と data/ も引き継がない（前提 7）。写すと、ボリュームの丸写しでホストのディスクが埋まる落とし穴（AGENTS.md）に当たる
• 前提 4（後片付け）: devbase は旧形式の VS Code Server ボリュームを消さない（C4）。devbase up が見つけたときに名前と消し方を案内し、消すのは利用者が行う
• 前提 5（本体の旧版の片付け）: Dev Containers 拡張（0.469.0 で確かめた）は、devbase の attach の形では bin/ の旧版を消さない（「実機で確かめることの扱い」の 2）。devbase のコンテナの起動で、bin/ の版を新しい順に一定の数だけ残して古い版を消す。残す数は設計で決め、3 版以上とする
• 前提 6（片付けの置き場）: 本体の旧版の片付けと、権限の用意は、コンテナの entrypoint（devbase_setup_vscode_server_dir）に置く。entrypoint の変更は base を建て直すまで効かない（AGENTS.md の落とし穴）。この課題で base の道具とその版は変えない（P1 に当たらない）
• 前提 7（作り直しで失うもの）: devbase up の作り直しのたびに、コンテナの書き込みレイヤーにある次のものが消える。利用者が承認ゲート 1（2026-10-14）で、conductor が動いているコンテナ 2 つで測った値を見て受け入れた
  • data/User/History（ローカル履歴、約 300KB）
  • data/User/globalStorage と data/User/workspaceStorage（拡張のリモート側の状態。Copilot Chat など、約 250KB）
  • data/logs（約 16MB。消えるため溜まらなくなる）
  • 手で入れたリモート側の設定（data/Machine/settings.json の window.title 以外）と、手で入れた拡張。Dev Containers の既定の拡張は .installExtensionsMarker が消えるため、作り直しの後の attach で入り直す
  • 接続トークンと .devport は作り直される。window.title は devbase up が毎回書き直す
• 前提 7（拡張の集まり）: 拡張は全コンテナで同じ集まりになる。（以下略）（2026-10-14 に削除。拡張を共有しないため当たらない）

対象範囲

含む:

• 共通の VS Code Server ボリュームを作る・dev インスタンスの ~/.vscode-server/bin へ付ける（lib/devbase/volume/manager.py・lib/devbase/volume/compose.py）
• コンテナの起動で ~/.vscode-server と ~/.vscode-server/bin を開発ユーザーが書ける形にし、bin/ の旧版と同時の展開の残りを片付ける（containers/base/entrypoint.sh の devbase_setup_vscode_server_dir）
• devbase up が旧形式の VS Code Server ボリュームを見つけたときの案内
• 文書（docs/user/container-operations.md の「VS Code Server の永続化」とボリュームの表）、CHANGELOG.md の [Unreleased]
• 上の振る舞いのテスト（tests/volume/・tests/containers/）

含まない:

• 旧形式の VS Code Server ボリュームを devbase が消す・写す・付けること
• extensions/・extensionsCache/・data/ を作り直しをまたいで残すこと（前提 1・7。利用者の決定）
• 拡張の版の選び方・自動更新の振る舞いを変えること（VS Code と Dev Containers 拡張の持ち物）
• extensionsCache/ と extensions/ の旧版の片付け（書き込みレイヤーにあり、devbase up の作り直しで消える）
• スナップショットの対象を変えること
• Cursor など ~/.vscode-server 以外のサーバーの置き場（~/.cursor-server など）
• base イメージに入れる道具とその版の変更（P1）

実機で確かめることの扱い

担当が確かめたのは、新しく作った空の作業用ボリューム issue463-scratch-vscs と手元の devbase-base:latest（sha256:2bf59f64…、作成 2026-10-12T17:19:13Z、arm64、macOS の Docker Desktop）の docker run --rm で、VS Code Server 1.140.0（commit 07f806f9）と 1.139.0 を動かした範囲である（2026-10-13）。Dev Containers 拡張の手順は、手元の ms-vscode-remote.remote-containers-0.469.0 の dist/extension/extension.js を読んで写した。実の VS Code からの attach はしていない。4〜10 は extensions/ と data/ を共有する案のために確かめたもので、2026-10-14 に共有を bin/ に絞ったため、確認は要らなくなった。結果は記録として残す。

ドメインイベント

用語

受け入れ条件

ボリュームと compose:

• 1. devbase up / devbase scale は、共通の VS Code Server ボリュームが無ければ 1 本作り、あれば作らない。プロジェクト・インスタンス・アカウントグループが違っても同じ 1 本である
• 2. 生成した compose の dev インスタンスは、どれも共通の VS Code Server ボリュームを /home/ubuntu/.vscode-server/bin に付け、/home/ubuntu/.vscode-server と /home/ubuntu/.vscode-server/data にはボリュームを付けない
• 2. 生成した compose の dev インスタンスは、どれも共通の VS Code Server ボリュームを /home/ubuntu/.vscode-server に付け、インスタンスごとに違うボリュームを /home/ubuntu/.vscode-server/data に付ける → 上の 2 へ変更（2026-10-14、利用者の決定）
• 3. 共通の VS Code Server ボリュームの名前は、どのプロジェクト名・インスタンス番号の旧形式の VS Code Server ボリュームの名前（devbase_vscode_<project>_<index>）とも重ならず、旧形式の案内が旧形式として選ばない
• 3. コンテナごとの VS Code Server の状態のボリュームの名前は、プロジェクトとインスタンス番号で決まり、どのプロジェクト名でも、旧形式の VS Code Server ボリュームの名前とも共通の VS Code Server ボリュームの名前とも重ならない → 上の 3 へ変更（2026-10-14、コンテナごとのボリュームを作らない）
• 4. 前提: コンテナ A とコンテナ B（別のプロジェクト）が共通の VS Code Server ボリュームを付けている。操作: A で本体を bin/<commit> に置く。結果: B から ~/.vscode-server/bin/<commit>/bin/code-server --version が通る
• 4. （A の code-server で拡張を入れると、B の code-server --list-extensions にその拡張が出る） → 上の 4 へ変更（2026-10-14、拡張を共有しない）
• 5. プロジェクトの compose が /home/ubuntu/.vscode-server か /home/ubuntu/.vscode-server/bin を自分で付けているとき、devbase はボリュームを足さない
• 5. プロジェクトの compose が /home/ubuntu/.vscode-server を自分で付けているとき、devbase は ~/.vscode-server にも ~/.vscode-server/data にもボリュームを足さない（今と同じ） → 上の 5 へ変更（2026-10-14、マウント先が bin になった）
• 6. 生成した compose に、旧形式の VS Code Server ボリュームが現れない

コンテナの起動:

• 7. 前提: 共通の VS Code Server ボリュームの bin/ に、残す数より多い版がある。操作: コンテナを起動する。結果: 新しい順に残す数の版だけが残り、それより古い版のディレクトリが無い
• 8. 前提: bin/<commit>/ の中に、同時の展開で残った入れ子の本体（vscode-server-linux-* など、product.json を持つディレクトリ）がある。操作: コンテナを起動する。結果: 入れ子の本体が無く、bin/<commit>/bin/code-server は残っている
• 9. 片付けで消せないもの（権限が無い・ほかのコンテナが先に消した）があっても、コンテナの起動は止まらず、消せなかったパスを WARNING の行に出す（ほかのコンテナが先に消したときは出さない）
• 10. 空のボリュームを ~/.vscode-server/bin に付けて起動すると、~/.vscode-server と ~/.vscode-server/bin は開発ユーザーが書ける。この課題より前の entrypoint を持つイメージ（建て直す前の base と、その上の派生イメージ）でも、devbase up の起動の後の処理の後には ~/.vscode-server/bin を開発ユーザーが書ける
• 10. 空のボリュームを付けて起動すると、~/.vscode-server と ~/.vscode-server/data は開発ユーザーが書ける。この課題より前の entrypoint を持つイメージでも、~/.vscode-server/data は開発ユーザーが書ける → 上の 10 へ変更（2026-10-14、マウント先が bin になった）

移り方と後片付け:

• 11. 前提: 旧形式の VS Code Server ボリュームが 1 本以上ある。操作: devbase up。結果: 旧形式のボリュームの名前と、消すコマンドが案内に出る。devbase はそのボリュームを消さず、付けず、中身を読まない
• 12. 前提: 旧形式の VS Code Server ボリュームが無い。操作: devbase up。結果: 案内は出ない
• 13. スナップショットの対象は変わらない（共通の VS Code Server ボリュームは対象外）

文書:

• 14. docs/user/container-operations.md の「VS Code Server の永続化」とボリュームの表が、共有するのは bin/ だけであること、共有する理由、extensions/・extensionsCache/・data/ はコンテナの書き込みレイヤーにあり devbase up の作り直しで消え docker restart と端末の再起動では消えないこと、作り直しで失うもの（前提 7 の項目。Dev Containers の既定の拡張は入り直すこと）、移ったあとの最初の attach で本体を取り直すこと、旧形式のボリュームの消し方、bin/ に残す版の数を書いている。「接続トークンを奪い合う」という記述が無い
• 14. （共有する置き場とコンテナごとの置き場、data/ を分ける理由（.devport と window.title）、手で入れた拡張を入れ直すことを書く） → 上の 14 へ変更（2026-10-14、利用者の決定）
• 15. CHANGELOG.md の [Unreleased] に、ボリュームの構成が変わること、最初の attach で本体を取り直すこと、拡張とリモート側の設定・状態が devbase up の作り直しのたびに消えるようになること、旧形式のボリュームを利用者が消すことを書いている
• 15. （ボリュームの構成が変わること、最初の attach で取り直すこと、旧形式のボリュームを利用者が消すこと） → 上の 15 へ変更（2026-10-14、作り直しで消えるものが増えた）

非機能の条件

影響

検証手段

手動確認の項目:

• M1（マージ前）: 別のプロジェクトの 2 つのコンテナへ VS Code を attach する。2 つ目の attach が本体を取り直さず、共通の VS Code Server ボリュームの bin/<commit> で繋がる。両方の窓が使え、窓のタイトルがそれぞれのコンテナ名で始まり、片方の窓の「ウィンドウの再読み込み」で同じコンテナへ繋がり直す。片方のプロジェクトで devbase up を打ち直した後に attach し直すと、Dev Containers の既定の拡張が入り直して使える
• M2（マージ前）: 拡張の同時のインストール・更新（2026-10-14 に削除。拡張を共有しない）
• M3（マージ前）: .obsolete の消去と動いている窓（2026-10-14 に削除。拡張を共有しない）
• M4（リリース後）: 片方の端末の VS Code だけを更新し、版の違う 2 つの窓が同じ共通の VS Code Server ボリュームの bin/ を使う。どちらの窓も使え、コンテナの起動の片付けがどちらの版も消さない
• M5（リリース後）: VS Code の更新の後、複数の窓を一度に開き直す。その後にコンテナを起動し直すと、bin/<新しい commit>/ に入れ子の本体が残っていない

前提とする取り決め

境界

未決

MVV との突き合わせ

Value 2（作り直しで失わない）に反する疑いがある。手で入れたリモート側の設定・手で入れた拡張・ローカル履歴・拡張のリモート側の状態が、devbase up の作り直しで消える（前提 7）。利用者が承認ゲート 1（2026-10-14）で、測った量を見て受け入れた。共通原則の優先順位で、利用者の承認はプロジェクトの MVV より上にある。ほかは反する疑いが無い。根拠: Value 1（本体を取り直すのは移った後の最初の 1 回だけ。既定の拡張は作り直しの後に入り直す）、Value 2（上のとおり）、Value 3（共有するのは本体だけで、プロジェクトの設定・機密・データ・拡張を共有しない）、C4（旧形式のボリュームを devbase が消さない）、P1（base の道具とその版を変えない）、P3（マージ前の手動確認の devbase up は承認を取ってから打つ）。

進行

モード: —

• 要求と受け入れ条件 — 2026-10-13 08:57
• 作業場所の用意 — 2026-10-14 09:42
• 設計 — 2026-10-13 09:09
• 素材の収集と出典の確定
• ドキュメント再構成
• ドキュメントレビュー
• 計画 — 2026-10-14 09:42
• 実装 — 2026-10-14 09:42
• 構造改善 — 2026-10-14 10:18
• 実装レビュー — 2026-10-14 10:36
• 完了判定 — 2026-10-14 09:53
• Pull Request — 2026-10-14 09:57
• 確定仕様化 — 2026-10-14 12:38
• 後片付け
• 配布 — 2026-10-14 13:52
• 体裁レビュー
• リリース後テスト — 2026-10-14 13:53
• 振り返り — 2026-10-14 13:58
• 棚卸し — 2026-10-15 13:18

振り返り: #488 (comment)