diff --git a/site/content/_index.de.md b/site/content/_index.de.md
new file mode 100644
index 0000000..057edd8
--- /dev/null
+++ b/site/content/_index.de.md
@@ -0,0 +1,90 @@
+---
+title: Composia
+layout: hextra-home
+---
+
+{{< hextra/hero-badge link="https://forgejo.alexma.top/alexma233/composia" >}}
+
+ Frei und Open Source
+ {{< icon name="arrow-circle-right" attributes="height=14" >}}
+{{< /hextra/hero-badge >}}
+
+
+{{< hextra/hero-headline >}}
+ Deine Compose-Dateien, überall
+{{< /hextra/hero-headline >}}
+
+
+
+{{< hextra/hero-subtitle >}}
+ Ein selbst gehostetes Orchestrierungssystem für Power-User.
Definiere Dienste als Klartext, verwalte sie in Git, bleib datenbankfrei und ohne Lock-in.
Backups, DNS, Reverse-Proxying und Image-Updates — alles inklusive.
+{{< /hextra/hero-subtitle >}}
+
+
+
+{{< hextra/hero-button text="Schnellstart" link="docs" >}}
+{{< hextra/hero-button text="Repository" link="https://forgejo.alexma.top/alexma233/composia" style="background-color: transparent; border: 1px solid var(--tw-prose-headings); color: var(--tw-prose-headings);" >}}
+
+
+
+
+{{< hextra/feature-grid >}}
+
+{{< hextra/feature-card
+ title="Multi-Node Compose"
+ subtitle="Deploy Dienste auf beliebige Nodes mit einer einfachen Konfiguration. Einzigartiger Verbindungsmodus funktioniert über NAT, Firewalls und CDNs hinweg."
+ icon="server"
+ style="background: radial-gradient(ellipse at 50% 80%,rgba(236,72,153,0.1),hsla(0,0%,100%,0));"
+>}}
+
+{{< hextra/feature-card
+ title="Standard-Dateien, kein Lock-in"
+ subtitle="docker-compose.yaml + composia-meta.yaml, gespeichert in deinem Git-Repository. Offene Formate, datenbankfreie Speicherung, manuelle Kontrolle jederzeit."
+ icon="lock-open"
+ style="background: radial-gradient(ellipse at 50% 80%,rgba(16,185,129,0.1),hsla(0,0%,100%,0));"
+>}}
+
+{{< hextra/feature-card
+ title="Einfach zu bedienendes Web-Dashboard"
+ subtitle="Datei-Browsing und -Bearbeitung, Live-Logs, Docker-Ressourcenansichten und interaktive Terminals. Mobil-freundlich, mit allem, was du brauchst, um Dienste vom Browser aus zu verwalten."
+ icon="desktop-computer"
+ style="background: radial-gradient(ellipse at 50% 80%,rgba(37,99,235,0.12),hsla(0,0%,100%,0));"
+>}}
+
+{{< hextra/feature-card
+ title="CLI und öffentliche API"
+ subtitle="Eine voll ausgestattete CLI, bereit für Automatisierungsskripte und KI-Agenten. Öffentliche APIs machen Drittanbieter-Clients einfach zu erstellen."
+ icon="terminal"
+>}}
+
+{{< hextra/feature-card
+ title="Backup und Restore"
+ subtitle="Automatisierte Backups mit Rustic, mit geplanten Durchläufen, Snapshot-Management und On-Demand-Restores."
+ icon="save"
+>}}
+
+{{< hextra/feature-card
+ title="DNS und Reverse-Proxy"
+ subtitle="Cloudflare-DNS-Management und Caddy-Reverse-Proxying funktionieren sofort. Synchronisiere und lade deine Caddyfile automatisch neu."
+ icon="globe"
+>}}
+
+{{< hextra/feature-card
+ title="Image-Update-Erkennung"
+ subtitle="Erkenne automatisch neue Docker-Image-Tags und wende Updates an. Unterstützt mehrere Versionierungsstrategien und kann die neuesten Tags von GitHub, Forgejo und mehr abrufen."
+ icon="arrow-circle-up"
+>}}
+
+{{< hextra/feature-card
+ title="Integrierte Benachrichtigungen"
+ subtitle="E-Mail-, Telegram- und Alertmanager-Benachrichtigungen für Aufgabenergebnisse, Backup-Ereignisse, Image-Updates und Node-Statusänderungen."
+ icon="bell"
+>}}
+
+{{< hextra/feature-card
+ title="Und mehr…"
+ icon="sparkles"
+ subtitle="Aufgabensystem / verschlüsselte Secrets / automatische Deployments / Prometheus-Metriken / plattformübergreifende Unterstützung / Barrierefreiheit / und mehr…"
+>}}
+
+{{< /hextra/feature-grid >}}
diff --git a/site/content/_index.fr.md b/site/content/_index.fr.md
new file mode 100644
index 0000000..380db5a
--- /dev/null
+++ b/site/content/_index.fr.md
@@ -0,0 +1,90 @@
+---
+title: Composia
+layout: hextra-home
+---
+
+{{< hextra/hero-badge link="https://forgejo.alexma.top/alexma233/composia" >}}
+
+ Libre et open source
+ {{< icon name="arrow-circle-right" attributes="height=14" >}}
+{{< /hextra/hero-badge >}}
+
+
+{{< hextra/hero-headline >}}
+ Vos fichiers Compose, partout
+{{< /hextra/hero-headline >}}
+
+
+
+{{< hextra/hero-subtitle >}}
+ Un système d'orchestration auto-hébergé conçu pour les utilisateurs expérimentés.
Définissez les services en texte brut, versionnez-les avec Git, sans base de données et sans dépendance propriétaire.
Sauvegardes, DNS, reverse proxy et mises à jour d'images — tout inclus.
+{{< /hextra/hero-subtitle >}}
+
+
+
+{{< hextra/hero-button text="Démarrage rapide" link="docs" >}}
+{{< hextra/hero-button text="Dépôt" link="https://forgejo.alexma.top/alexma233/composia" style="background-color: transparent; border: 1px solid var(--tw-prose-headings); color: var(--tw-prose-headings);" >}}
+
+
+
+
+{{< hextra/feature-grid >}}
+
+{{< hextra/feature-card
+ title="Compose multi-nœud"
+ subtitle="Déployez des services sur n'importe quel nœud à partir d'une configuration simple. Un mode de connexion unique fonctionne à travers NAT, pare-feu et CDN."
+ icon="server"
+ style="background: radial-gradient(ellipse at 50% 80%,rgba(236,72,153,0.1),hsla(0,0%,100%,0));"
+>}}
+
+{{< hextra/feature-card
+ title="Fichiers standards, sans dépendance"
+ subtitle="docker-compose.yaml + composia-meta.yaml, stockés dans votre dépôt Git. Formats ouverts, stockage sans base de données, contrôle manuel à tout moment."
+ icon="lock-open"
+ style="background: radial-gradient(ellipse at 50% 80%,rgba(16,185,129,0.1),hsla(0,0%,100%,0));"
+>}}
+
+{{< hextra/feature-card
+ title="Interface web facile à utiliser"
+ subtitle="Navigation et édition de fichiers, logs en direct, vues des ressources Docker et terminaux interactifs. Adapté aux mobiles, avec tout ce dont vous avez besoin pour gérer les services depuis un navigateur."
+ icon="desktop-computer"
+ style="background: radial-gradient(ellipse at 50% 80%,rgba(37,99,235,0.12),hsla(0,0%,100%,0));"
+>}}
+
+{{< hextra/feature-card
+ title="CLI et API publique"
+ subtitle="Une CLI complète prête pour les scripts d'automatisation et les agents IA. Les API publiques facilitent la création de clients tiers."
+ icon="terminal"
+>}}
+
+{{< hextra/feature-card
+ title="Sauvegarde et restauration"
+ subtitle="Sauvegardes automatisées basées sur Rustic, avec exécutions planifiées, gestion des snapshots et restaurations à la demande."
+ icon="save"
+>}}
+
+{{< hextra/feature-card
+ title="DNS et reverse proxy"
+ subtitle="La gestion DNS Cloudflare et le reverse proxy Caddy fonctionnent immédiatement. Synchronisez et rechargez automatiquement votre Caddyfile."
+ icon="globe"
+>}}
+
+{{< hextra/feature-card
+ title="Détection des mises à jour d'images"
+ subtitle="Détectez automatiquement les nouvelles balises d'images Docker et appliquez les mises à jour. Prend en charge plusieurs stratégies de versionnement et peut récupérer les dernières balises depuis GitHub, Forgejo et plus encore."
+ icon="arrow-circle-up"
+>}}
+
+{{< hextra/feature-card
+ title="Notifications intégrées"
+ subtitle="Notifications par e-mail, Telegram et Alertmanager pour les résultats de tâches, les événements de sauvegarde, les mises à jour d'images et les changements d'état des nœuds."
+ icon="bell"
+>}}
+
+{{< hextra/feature-card
+ title="Et plus encore…"
+ icon="sparkles"
+ subtitle="Système de tâches / secrets chiffrés / déploiements automatiques / métriques Prometheus / support multi-plateforme / accessibilité / et plus encore…"
+>}}
+
+{{< /hextra/feature-grid >}}
diff --git a/site/content/_index.ja.md b/site/content/_index.ja.md
new file mode 100644
index 0000000..e871907
--- /dev/null
+++ b/site/content/_index.ja.md
@@ -0,0 +1,90 @@
+---
+title: Composia
+layout: hextra-home
+---
+
+{{< hextra/hero-badge link="https://forgejo.alexma.top/alexma233/composia" >}}
+
+ フリー＆オープンソース
+ {{< icon name="arrow-circle-right" attributes="height=14" >}}
+{{< /hextra/hero-badge >}}
+
+
+{{< hextra/hero-headline >}}
+ あなたの Compose ファイルを、どこでも
+{{< /hextra/hero-headline >}}
+
+
+
+{{< hextra/hero-subtitle >}}
+ パワーユーザーのために作られたセルフホスト型オーケストレーションシステム。
サービスをプレーンテキストで定義し、Git で管理、データベース不要・ロックイン不要。
バックアップ、DNS、リバースプロキシ、イメージ更新 — すべて標準装備。
+{{< /hextra/hero-subtitle >}}
+
+
+
+{{< hextra/hero-button text="クイックスタート" link="docs" >}}
+{{< hextra/hero-button text="リポジトリ" link="https://forgejo.alexma.top/alexma233/composia" style="background-color: transparent; border: 1px solid var(--tw-prose-headings); color: var(--tw-prose-headings);" >}}
+
+
+
+
+{{< hextra/feature-grid >}}
+
+{{< hextra/feature-card
+ title="マルチノード Compose"
+ subtitle="シンプルな設定で任意のノードにサービスをデプロイ。独自の接続モードが NAT、ファイアウォール、CDN を越えて動作します。"
+ icon="server"
+ style="background: radial-gradient(ellipse at 50% 80%,rgba(236,72,153,0.1),hsla(0,0%,100%,0));"
+>}}
+
+{{< hextra/feature-card
+ title="標準ファイル、ロックインなし"
+ subtitle="Git リポジトリに保存する docker-compose.yaml + composia-meta.yaml。オープンフォーマット、データベースフリーストレージ、いつでも手動操作可能。"
+ icon="lock-open"
+ style="background: radial-gradient(ellipse at 50% 80%,rgba(16,185,129,0.1),hsla(0,0%,100%,0));"
+>}}
+
+{{< hextra/feature-card
+ title="使いやすい Web ダッシュボード"
+ subtitle="ファイルの閲覧と編集、ライブログ、Docker リソースビュー、インタラクティブターミナル。モバイル対応、ブラウザからすべてのサービス管理が可能。"
+ icon="desktop-computer"
+ style="background: radial-gradient(ellipse at 50% 80%,rgba(37,99,235,0.12),hsla(0,0%,100%,0));"
+>}}
+
+{{< hextra/feature-card
+ title="CLI とパブリック API"
+ subtitle="自動化スクリプトや AI エージェントに対応したフル機能の CLI。公開 API によりサードパーティクライアントの構築も容易。"
+ icon="terminal"
+>}}
+
+{{< hextra/feature-card
+ title="バックアップとリストア"
+ subtitle="Rustic による自動バックアップ。スケジュール実行、スナップショット管理、オンデマンドリストアに対応。"
+ icon="save"
+>}}
+
+{{< hextra/feature-card
+ title="DNS とリバースプロキシ"
+ subtitle="Cloudflare DNS 管理と Caddy リバースプロキシがそのまま動作。Caddyfile を自動同期・リロード。"
+ icon="globe"
+>}}
+
+{{< hextra/feature-card
+ title="イメージ更新検出"
+ subtitle="新しい Docker イメージタグを自動検出して更新を適用。複数のバージョニング戦略に対応し、GitHub、Forgejo などから最新タグを取得可能。"
+ icon="arrow-circle-up"
+>}}
+
+{{< hextra/feature-card
+ title="ビルトイン通知"
+ subtitle="タスク結果、バックアップイベント、イメージ更新、ノード状態変化を Email、Telegram、Alertmanager で通知。"
+ icon="bell"
+>}}
+
+{{< hextra/feature-card
+ title="その他…"
+ icon="sparkles"
+ subtitle="タスクシステム / 暗号化シークレット / 自動デプロイ / Prometheus メトリクス / クロスプラットフォーム対応 / アクセシビリティ / その他…"
+>}}
+
+{{< /hextra/feature-grid >}}
diff --git a/site/content/_index.zh-hans.md b/site/content/_index.zh-hans.md
index f906660..96f5dde 100644
--- a/site/content/_index.zh-hans.md
+++ b/site/content/_index.zh-hans.md
@@ -5,7 +5,7 @@ layout: hextra-home
{{< hextra/hero-badge link="https://forgejo.alexma.top/alexma233/composia" >}}
- 自由且开源
+ 自由开源
{{< icon name="arrow-circle-right" attributes="height=14" >}}
{{< /hextra/hero-badge >}}
@@ -17,13 +17,13 @@ layout: hextra-home
{{< hextra/hero-subtitle >}}
- 为高阶用户精心打造的自托管编排系统。
用纯文本定义服务，放在 Git 仓库，无数据库，无锁定。
备份、DNS、反向代理、镜像更新都一应俱全。
+ 为进阶用户打造的自托管编排系统。
用纯文本定义服务，用 Git 管理，无需数据库、无平台绑定。
备份、DNS、反向代理和镜像更新——全部内置。
{{< /hextra/hero-subtitle >}}
{{< hextra/hero-button text="快速开始" link="docs" >}}
-{{< hextra/hero-button text="代码仓库" link="https://forgejo.alexma.top/alexma233/composia" style="background-color: transparent; border: 1px solid var(--tw-prose-headings); color: var(--tw-prose-headings);" >}}
+{{< hextra/hero-button text="仓库地址" link="https://forgejo.alexma.top/alexma233/composia" style="background-color: transparent; border: 1px solid var(--tw-prose-headings); color: var(--tw-prose-headings);" >}}
@@ -32,59 +32,59 @@ layout: hextra-home
{{< hextra/feature-card
title="多节点 Compose"
- subtitle="从一份简单的配置，部署服务到任意节点。独特的连接模式穿透 NAT、防火墙与 CDN。"
+ subtitle="通过简单的配置将服务部署到任意节点。独有的连接模式可穿透 NAT、防火墙和 CDN。"
icon="server"
style="background: radial-gradient(ellipse at 50% 80%,rgba(236,72,153,0.1),hsla(0,0%,100%,0));"
>}}
{{< hextra/feature-card
- title="标准文件，无锁定"
- subtitle="docker-compose.yaml + composia-meta.yaml，保存在你的 Git 仓库。无专有格式和数据库，随时手动操作。"
+ title="标准文件，无平台绑定"
+ subtitle="docker-compose.yaml + composia-meta.yaml，存储在 Git 仓库中。开放格式，无数据库存储，随时可手动控制。"
icon="lock-open"
style="background: radial-gradient(ellipse at 50% 80%,rgba(16,185,129,0.1),hsla(0,0%,100%,0));"
>}}
{{< hextra/feature-card
- title="易用的 Web 面板"
- subtitle="文件浏览和编辑、实时日志、Docker 资源查看、交互式终端。移动端友好，用浏览器管理服务所需的一切。"
+ title="易用的 Web 仪表盘"
+ subtitle="文件浏览与编辑、实时日志、Docker 资源查看和交互式终端。支持移动端，满足从浏览器管理服务的所有需求。"
icon="desktop-computer"
style="background: radial-gradient(ellipse at 50% 80%,rgba(37,99,235,0.12),hsla(0,0%,100%,0));"
>}}
{{< hextra/feature-card
title="CLI 与公共 API"
- subtitle="功能完备的 CLI，为自动化脚本和 AI Agent 准备好。公开 API，助力第三方客户端。"
+ subtitle="功能齐全的 CLI，可用于自动化脚本和 AI 智能体。公共 API 让第三方客户端易于构建。"
icon="terminal"
>}}
{{< hextra/feature-card
title="备份与恢复"
- subtitle="基于 Rustic 的自动备份，定时调度、快照管理、按需恢复。将安全放在第一位。"
+ subtitle="由 Rustic 驱动的自动备份，支持定时运行、快照管理和按需恢复。"
icon="save"
>}}
{{< hextra/feature-card
title="DNS 与反向代理"
- subtitle="Cloudflare DNS 管理与 Caddy 反向代理开箱即用。自动同步并重载 Caddyfile。"
+ subtitle="Cloudflare DNS 管理和 Caddy 反向代理开箱即用。自动同步并重载 Caddyfile。"
icon="globe"
>}}
{{< hextra/feature-card
title="镜像更新检测"
- subtitle="自动检测 Docker 镜像新 Tag，并应用更新。支持各种版本策略，也可从 GitHub、Forgejo 等平台获取最新 Tag。"
+ subtitle="自动检测新的 Docker 镜像标签并应用更新。支持多种版本策略，可从 GitHub、Forgejo 等获取最新标签。"
icon="arrow-circle-up"
>}}
{{< hextra/feature-card
title="内置通知"
- subtitle="邮件 / Telegram / Alertmanager 通知，覆盖任务结果、备份事件、镜像更新、节点上下线。"
+ subtitle="邮件、Telegram 和 Alertmanager 通知，覆盖任务结果、备份事件、镜像更新和节点状态变化。"
icon="bell"
>}}
{{< hextra/feature-card
- title="还有更多…"
+ title="还有更多……"
icon="sparkles"
- subtitle="任务系统 / 加密 Secrets / 自动部署 / Prometheus metrics / 全平台支持 / 无障碍 / 等等…"
+ subtitle="任务系统 / 加密密钥 / 自动部署 / Prometheus 指标 / 跨平台支持 / 无障碍访问 / 更多……"
>}}
{{< /hextra/feature-grid >}}
diff --git a/site/content/_index.zh-hant.md b/site/content/_index.zh-hant.md
new file mode 100644
index 0000000..ab5737d
--- /dev/null
+++ b/site/content/_index.zh-hant.md
@@ -0,0 +1,90 @@
+---
+title: Composia
+layout: hextra-home
+---
+
+{{< hextra/hero-badge link="https://forgejo.alexma.top/alexma233/composia" >}}
+
+ 自由且開放原始碼
+ {{< icon name="arrow-circle-right" attributes="height=14" >}}
+{{< /hextra/hero-badge >}}
+
+
+{{< hextra/hero-headline >}}
+ 您的 Compose 檔案，無所不在
+{{< /hextra/hero-headline >}}
+
+
+
+{{< hextra/hero-subtitle >}}
+ 為進階使用者打造的自託管協調系統。
以純文字定義服務、存放在 Git 中、無需資料庫且無鎖定。
備份、DNS、反向代理與映像檔更新——全部內建。
+{{< /hextra/hero-subtitle >}}
+
+
+
+{{< hextra/hero-button text="快速開始" link="docs" >}}
+{{< hextra/hero-button text="存放庫" link="https://forgejo.alexma.top/alexma233/composia" style="background-color: transparent; border: 1px solid var(--tw-prose-headings); color: var(--tw-prose-headings);" >}}
+
+
+
+
+{{< hextra/feature-grid >}}
+
+{{< hextra/feature-card
+ title="多節點 Compose"
+ subtitle="從簡單的設定檔將服務部署到任意節點。獨特的連線模式可穿透 NAT、防火牆與 CDN。"
+ icon="server"
+ style="background: radial-gradient(ellipse at 50% 80%,rgba(236,72,153,0.1),hsla(0,0%,100%,0));"
+>}}
+
+{{< hextra/feature-card
+ title="標準檔案，無鎖定"
+ subtitle="docker-compose.yaml + composia-meta.yaml，存放在您的 Git 存放庫中。開放格式、無資料庫儲存、隨時手動控制。"
+ icon="lock-open"
+ style="background: radial-gradient(ellipse at 50% 80%,rgba(16,185,129,0.1),hsla(0,0%,100%,0));"
+>}}
+
+{{< hextra/feature-card
+ title="易用的 Web 儀表板"
+ subtitle="檔案瀏覽與編輯、即時日誌、Docker 資源檢視與互動式終端機。支援行動裝置，提供從瀏覽器管理服務所需的一切功能。"
+ icon="desktop-computer"
+ style="background: radial-gradient(ellipse at 50% 80%,rgba(37,99,235,0.12),hsla(0,0%,100%,0));"
+>}}
+
+{{< hextra/feature-card
+ title="CLI 與公開 API"
+ subtitle="功能齊全的 CLI，適用於自動化腳本與 AI 代理。公開 API 讓第三方客戶端易於建置。"
+ icon="terminal"
+>}}
+
+{{< hextra/feature-card
+ title="備份與還原"
+ subtitle="由 Rustic 驅動的自動化備份，支援排程執行、快照管理與隨需還原。"
+ icon="save"
+>}}
+
+{{< hextra/feature-card
+ title="DNS 與反向代理"
+ subtitle="Cloudflare DNS 管理與 Caddy 反向代理開箱即用。自動同步並重新載入您的 Caddyfile。"
+ icon="globe"
+>}}
+
+{{< hextra/feature-card
+ title="映像檔更新偵測"
+ subtitle="自動偵測新的 Docker 映像檔標籤並套用更新。支援多種版本策略，可從 GitHub、Forgejo 等來源取得最新標籤。"
+ icon="arrow-circle-up"
+>}}
+
+{{< hextra/feature-card
+ title="內建通知"
+ subtitle="Email、Telegram 與 Alertmanager 通知，涵蓋任務結果、備份事件、映像檔更新與節點狀態變更。"
+ icon="bell"
+>}}
+
+{{< hextra/feature-card
+ title="還有更多…"
+ icon="sparkles"
+ subtitle="任務系統 / 加密密鑰 / 自動部署 / Prometheus 指標 / 跨平台支援 / 無障礙 / 以及更多…"
+>}}
+
+{{< /hextra/feature-grid >}}
diff --git a/site/content/docs/_index.de.md b/site/content/docs/_index.de.md
new file mode 100644
index 0000000..567a8dd
--- /dev/null
+++ b/site/content/docs/_index.de.md
@@ -0,0 +1,11 @@
+---
+title: "Dokumentation"
+date: '2026-05-13T16:52:58+08:00'
+weight: 10
+---
+
+- [Installation](installation/) — wähle eine Deployment-Methode und konfiguriere deine Instanz.
+- [Client](client/) — CLI und Web-UI, die beiden Wege, mit Composia zu interagieren.
+- [Leitfaden](guide/) — wie man jede Funktion nutzt: DNS, Backups, Secrets, Image-Updates, Benachrichtigungen und mehr.
+- [Entwickler-Leitfaden](developer-guide/) — Architektur, lokale Entwicklungseinrichtung, Protobuf-Codegenerierung, API-Referenz.
+- [Über](about/) — warum Composia existiert und Branding-Richtlinien.
diff --git a/site/content/docs/_index.fr.md b/site/content/docs/_index.fr.md
new file mode 100644
index 0000000..f8bdf5c
--- /dev/null
+++ b/site/content/docs/_index.fr.md
@@ -0,0 +1,11 @@
+---
+title: "Documentation"
+date: '2026-05-13T16:52:58+08:00'
+weight: 10
+---
+
+- [Installation](installation/) — choisissez une méthode de déploiement et configurez votre instance.
+- [Client](client/) — la CLI et l'interface web, les deux façons d'interagir avec Composia.
+- [Guide](guide/) — comment utiliser chaque fonctionnalité : DNS, sauvegardes, secrets, mises à jour d'images, notifications et plus encore.
+- [Guide développeur](developer-guide/) — architecture, configuration de développement local, génération de code protobuf, référence API.
+- [À propos](about/) — pourquoi Composia existe et les consignes de marque.
diff --git a/site/content/docs/_index.ja.md b/site/content/docs/_index.ja.md
new file mode 100644
index 0000000..aa055bb
--- /dev/null
+++ b/site/content/docs/_index.ja.md
@@ -0,0 +1,11 @@
+---
+title: "ドキュメント"
+date: '2026-05-13T16:52:58+08:00'
+weight: 10
+---
+
+- [インストール](installation/) — デプロイ方法の選択とインスタンスの設定。
+- [クライアント](client/) — CLI と Web UI、Composia と対話する 2 つの方法。
+- [ガイド](guide/) — 各機能の使い方: DNS、バックアップ、シークレット、イメージ更新、通知など。
+- [開発者ガイド](developer-guide/) — アーキテクチャ、ローカル開発環境、protobuf コード生成、API リファレンス。
+- [概要](about/) — Composia が存在する理由とブランディングガイドライン。
diff --git a/site/content/docs/_index.zh-hans.md b/site/content/docs/_index.zh-hans.md
index 27305b3..0c7fd6a 100644
--- a/site/content/docs/_index.zh-hans.md
+++ b/site/content/docs/_index.zh-hans.md
@@ -1,4 +1,11 @@
---
+title: "文档"
date: '2026-05-13T16:52:58+08:00'
-title: 'Docs'
+weight: 10
---
+
+- [安装](installation/) — 选择部署方式并配置您的实例。
+- [客户端](client/) — CLI 和 Web UI，与 Composia 交互的两种方式。
+- [指南](guide/) — 如何使用各项功能：DNS、备份、密钥、镜像更新、通知等。
+- [开发者指南](developer-guide/) — 架构、本地开发环境搭建、protobuf 代码生成、API 参考。
+- [关于](about/) — Composia 的定位与品牌指南。
diff --git a/site/content/docs/_index.zh-hant.md b/site/content/docs/_index.zh-hant.md
new file mode 100644
index 0000000..b224c7d
--- /dev/null
+++ b/site/content/docs/_index.zh-hant.md
@@ -0,0 +1,11 @@
+---
+title: "文件"
+date: '2026-05-13T16:52:58+08:00'
+weight: 10
+---
+
+- [安裝](installation/) — 選擇部署方式並設定您的執行實例。
+- [客戶端](client/) — CLI 與 Web UI，兩種與 Composia 互動的方式。
+- [指南](guide/) — 各功能的使用方式：DNS、備份、密鑰、映像檔更新、通知以及更多。
+- [開發者指南](developer-guide/) — 架構、本地開發環境設定、protobuf 程式碼產生、API 參考。
+- [關於](about/) — Composia 的設計理念與品牌指南。
diff --git a/site/content/docs/about/_index.de.md b/site/content/docs/about/_index.de.md
new file mode 100644
index 0000000..c35b479
--- /dev/null
+++ b/site/content/docs/about/_index.de.md
@@ -0,0 +1,7 @@
+---
+title: "Über"
+date: '2026-05-26T00:00:00+08:00'
+weight: 50
+---
+
+- [Warum Composia?](why-composia/) — Design-Philosophie, Vergleich mit anderen Tools und für wen es gedacht ist.
diff --git a/site/content/docs/about/_index.fr.md b/site/content/docs/about/_index.fr.md
new file mode 100644
index 0000000..2dbb038
--- /dev/null
+++ b/site/content/docs/about/_index.fr.md
@@ -0,0 +1,7 @@
+---
+title: "À propos"
+date: '2026-05-26T00:00:00+08:00'
+weight: 50
+---
+
+- [Pourquoi Composia ?](why-composia/) — philosophie de conception, comparaison avec d'autres outils et à qui il s'adresse.
diff --git a/site/content/docs/about/_index.ja.md b/site/content/docs/about/_index.ja.md
new file mode 100644
index 0000000..d0575ab
--- /dev/null
+++ b/site/content/docs/about/_index.ja.md
@@ -0,0 +1,7 @@
+---
+title: "概要"
+date: '2026-05-26T00:00:00+08:00'
+weight: 50
+---
+
+- [なぜ Composia か？](why-composia/) — 設計哲学、他のツールとの比較、対象ユーザー。
diff --git a/site/content/docs/about/_index.zh-hans.md b/site/content/docs/about/_index.zh-hans.md
new file mode 100644
index 0000000..64ec796
--- /dev/null
+++ b/site/content/docs/about/_index.zh-hans.md
@@ -0,0 +1,7 @@
+---
+title: "关于"
+date: '2026-05-26T00:00:00+08:00'
+weight: 50
+---
+
+- [为什么选择 Composia？](why-composia/) — 设计理念、与其他工具的对比，以及适用人群。
diff --git a/site/content/docs/about/_index.zh-hant.md b/site/content/docs/about/_index.zh-hant.md
new file mode 100644
index 0000000..8a060e9
--- /dev/null
+++ b/site/content/docs/about/_index.zh-hant.md
@@ -0,0 +1,7 @@
+---
+title: "關於"
+date: '2026-05-26T00:00:00+08:00'
+weight: 50
+---
+
+- [為什麼選擇 Composia？](why-composia/) — 設計理念、與其他工具的比較，以及適合的使用者。
diff --git a/site/content/docs/about/why-composia.de.md b/site/content/docs/about/why-composia.de.md
new file mode 100644
index 0000000..88e8064
--- /dev/null
+++ b/site/content/docs/about/why-composia.de.md
@@ -0,0 +1,83 @@
+---
+title: "Warum Composia"
+date: '2026-05-26T00:00:00+08:00'
+weight: 10
+---
+
+Composia ist eine selbst gehostete Steuerungsebene für Docker Compose. Definiere deine Dienste als einfache Dateien, deploye sie auf einen oder mehrere Nodes und erhalte eine einheitliche Übersicht über deine gesamte Infrastruktur.
+
+## Es ist kein PaaS
+
+Im Gegensatz zu selbst gehosteten PaaS-Plattformen ersetzt Composia deine Compose-Dateien nicht durch ein eigenes Anwendungsmodell. Deine Konfiguration lebt in standardmäßigen `docker-compose.yaml`- und `composia-meta.yaml`-Dateien, die dir gehören. Die Steuerungsebene koordiniert und berichtet, aber du behältst jederzeit direkten CLI- und dateibasierten Zugriff auf jeden Node.
+
+Schalte Composia aus und deine `docker compose`-Befehle funktionieren weiterhin. Jede Operation basiert auf standardmäßigen Docker- und Compose-Grundelementen. Es gibt keinen Lock-in.
+
+## Wie es sich vergleicht
+
+### Dockge, Dockman
+
+Dockge und Dockman machen die Verwaltung einzelner Compose-Stacks komfortabler. Sie konzentrieren sich auf Single-Node-Komfort mit einer Browser-UI.
+
+Composia teilt den dateizentrierten Ansatz, fügt aber Multi-Node-Koordination hinzu: deploye einen Dienst auf einen beliebigen konfigurierten Node, erhalte eine einheitliche Ansicht aller Dienste und Nodes in einem Dashboard und nutze ein Aufgabensystem, das jede Operation mit vollständigen Logs aufzeichnet. Die CLI ist für Skripting und Automatisierung gebaut, nicht nur für gelegentliche Nutzung.
+
+### Dokploy, Coolify
+
+Dokploy und Coolify sind selbst gehostete PaaS-Plattformen. Sie definieren ihr eigenes Anwendungsmodell, verwalten Build-Pipelines und abstrahieren die zugrunde liegende Infrastruktur. Sobald du sie verwendest, hängt dein Deployment-Workflow von ihren Abstraktionen ab.
+
+Composia verfolgt den entgegengesetzten Ansatz. Es arbeitet mit deinen bestehenden Compose-Dateien in deiner eigenen Verzeichnisstruktur. Es gibt keine Build-Pipeline, kein Anwendungsmodell zu lernen und keine Abstraktionsschicht zwischen dir und Docker. Composia koordiniert die Arbeit, die Docker erledigt — es versteckt Docker nicht hinter einer Plattformabstraktion.
+
+## Design-Entscheidungen
+
+### Datenbankfrei
+
+Composia verwendet SQLite für den Laufzeitzustand und Git für die Sollzustand-Konfiguration. Es gibt kein PostgreSQL, kein MySQL, keine externe Datenbankabhängigkeit.
+
+Sichere deine gesamte Composia-Installation, indem du dein Git-Repository und die SQLite-Datenbankdatei sicherst. Stelle sie auf einer neuen Maschine wieder her und du bist wieder online. Keine Datenbankmigrationen, keine Verbindungspools, kein separater Datenbankserver.
+
+### Standard-Dateien, keine Abstraktion
+
+Ein Dienst ist ein Verzeichnis, das `docker-compose.yaml` und `composia-meta.yaml` enthält. Du organisierst Verzeichnisse, wie du willst. Du kannst jede Datei hinzufügen, die ein Compose-Projekt benötigt: Env-Dateien, Konfigurationsvorlagen, Caddyfile, benutzerdefinierte Skripte.
+
+Composia liest diese Dateien aus deinem Git-Repository und erstellt Dienstpakete, die Agenten mit `docker compose` ausführen. Nichts wird konvertiert, übersetzt oder umgeschrieben. Deine Compose-Dateien sind die einzige Quelle der Wahrheit.
+
+### Git-nativ
+
+Der Controller speichert den Sollzustand in einem Git-Repository. Jede Änderung ist ein Commit mit Autor und Nachricht. Du erhältst Versionshistorie, Rollback-Fähigkeit und die Möglichkeit, mit einem entfernten Repository zu synchronisieren. Verwende jeden Git-Workflow, den du bereits kennst.
+
+### CLI und API zuerst
+
+Alles, was du in der Web-UI tun kannst, kannst du mit der `composia`-CLI tun. Die CLI verwendet dieselbe öffentliche API wie das Web-Frontend. Skripting, CI-Pipelines und KI-Agenten kommunizieren mit Composia über dieselbe Schnittstelle.
+
+Die Web-UI ist eine SvelteKit-Anwendung, die dieselbe Controller-API aufruft. Es gibt keine separate Management-API oder nur intern zugängliche Endpunkte.
+
+## Was du bekommst
+
+**Multi-Node-Deployment.** Definiere, auf welchen Nodes ein Dienst laufen soll, in `composia-meta.yaml`. Composia deployt den Dienst auf alle Ziel-Nodes und meldet den Status von jedem einzelnen.
+
+**Web-Dashboard.** Durchsuche und bearbeite Repo-Dateien, sieh Live-Container-Logs, inspiziere Docker-Ressourcen (Container, Images, Netzwerke, Volumes) und öffne interaktive Terminals in laufende Container. Das Dashboard funktioniert auf Mobilgeräten.
+
+**Backup und Restore.** Automatisierte Backups mit Rustic, mit geplanten Durchläufen, Snapshot-Management und On-Demand-Restores. Schütze Dateien, Verzeichnisse, benannte Volumes und PostgreSQL-Datenbanken.
+
+**DNS-Management.** Automatische DNS-Record-Erstellung für Cloudflare, AliDNS, DNSPod, Route53 und Huawei Cloud. Records werden beim Deploy synchronisiert und beim Stopp entfernt.
+
+**Reverse-Proxy.** Caddy-Integration, die dienstspezifische Caddyfile-Konfigurationen synchronisiert und Neuladungen automatisch auslöst. Generierte Konfigurationsdateien befinden sich auf dem Agenten und werden vom Caddy-Infrastrukturdienst importiert.
+
+**Image-Updates.** Automatische Erkennung neuer Image-Versionen aus Docker-Registries und GitHub-, GitLab- oder Forgejo-Releases. Unterstützt Semver-, Datums-, Regex- und Latest-Filter. Wende Updates automatisch an oder überprüfe sie vor der Anwendung.
+
+**Benachrichtigungen.** E-Mail- (SMTP), Telegram- und Alertmanager-Benachrichtigungen für Aufgabenergebnisse, Backup-Ereignisse, Image-Updates und Node-Statusänderungen. Filtere nach Ereignistyp und Aufgabenquelle.
+
+**Verschlüsselte Secrets.** Age-basierte Verschlüsselung für Dienst-Secret-Dateien. Secrets werden verschlüsselt im Repository gespeichert und nur auf dem Controller entschlüsselt. Agenten erhalten entschlüsselten Inhalt in Dienstpaketen, ohne jemals auf den privaten Schlüssel zuzugreifen.
+
+**Aufgabensystem.** Jede Operation ist eine nachverfolgte Aufgabe mit schrittweisem Fortschritt, vollständiger Log-Ausgabe und Abschlussstatus. Führe Aufgaben erneut aus, inspiziere Aufgabenschritte und verfolge Logs in Echtzeit.
+
+**Prometheus-Metriken.** Der Controller stellt Prometheus-Metriken auf seinem HTTP-Server bereit.
+
+## Für wen es gedacht ist
+
+Composia ist für Power-User und Operations-Teams gebaut, die:
+
+- Bereits Docker Compose verwenden und Multi-Node-Koordination ohne Änderung ihres Workflows wünschen.
+- Klartext-Konfiguration in Git dem Durchklicken eines Webformulars vorziehen.
+- Automatisierung (Backups, DNS, Updates) wünschen, aber ihre Compose-Dateien nicht einer Plattform übergeben wollen.
+- Eine CLI benötigen, die sie skripten und integrieren können, nicht nur eine Browser-UI.
+- Datenbankfreie, Lock-in-freie und abhängigkeitsarme Infrastruktur schätzen.
diff --git a/site/content/docs/about/why-composia.fr.md b/site/content/docs/about/why-composia.fr.md
new file mode 100644
index 0000000..3bc0b43
--- /dev/null
+++ b/site/content/docs/about/why-composia.fr.md
@@ -0,0 +1,83 @@
+---
+title: "Pourquoi Composia"
+date: '2026-05-26T00:00:00+08:00'
+weight: 10
+---
+
+Composia est un plan de contrôle auto-hébergé pour Docker Compose. Définissez vos services sous forme de fichiers texte, déployez-les sur un ou plusieurs nœuds et obtenez une visibilité unifiée sur votre infrastructure.
+
+## Ce n'est pas un PaaS
+
+Contrairement aux plateformes PaaS auto-hébergées, Composia ne remplace pas vos fichiers Compose par son propre modèle applicatif. Votre configuration réside dans des fichiers standards `docker-compose.yaml` et `composia-meta.yaml` que vous possédez. Le plan de contrôle coordonne et rapporte, mais vous conservez toujours un accès direct en CLI et par fichiers à chaque nœud.
+
+Éteignez Composia et vos commandes `docker compose` fonctionnent toujours. Chaque opération est construite sur des primitives Docker et Compose standard. Il n'y a aucune dépendance propriétaire.
+
+## Comparaison
+
+### Dockge, Dockman
+
+Dockge et Dockman rendent la gestion de piles Compose individuelles plus confortable. Ils se concentrent sur la commodité mono-nœud avec une interface navigateur.
+
+Composia partage l'approche orientée fichiers mais ajoute la coordination multi-nœud : déployez un service sur n'importe quel nœud configuré, obtenez une vue unifiée de tous les services et nœuds dans un seul tableau de bord, et utilisez un système de tâches qui enregistre chaque opération avec des logs complets. La CLI est conçue pour le scripting et l'automatisation, pas seulement pour une utilisation occasionnelle.
+
+### Dokploy, Coolify
+
+Dokploy et Coolify sont des plateformes PaaS auto-hébergées. Elles définissent leur propre modèle applicatif, gèrent des pipelines de build et abstraient l'infrastructure sous-jacente. Une fois que vous les adoptez, votre workflow de déploiement dépend de leurs abstractions.
+
+Composia adopte l'approche inverse. Il fonctionne avec vos fichiers Compose existants dans votre propre structure de répertoires. Il n'y a pas de pipeline de build, pas de modèle applicatif à apprendre et pas de couche d'abstraction entre vous et Docker. Composia coordonne le travail que Docker effectue — il ne cache pas Docker derrière une abstraction de plateforme.
+
+## Choix de conception
+
+### Sans base de données
+
+Composia utilise SQLite pour l'état d'exécution et Git pour la configuration de l'état désiré. Il n'y a pas de PostgreSQL, pas de MySQL, pas de dépendance à une base de données externe.
+
+Sauvegardez l'intégralité de votre installation Composia en sauvegardant votre dépôt Git et le fichier de base de données SQLite. Restaurez-les sur une nouvelle machine et vous êtes de nouveau en ligne. Pas de migrations de base de données, pas de pools de connexion, pas de serveur de base de données séparé.
+
+### Fichiers standards, sans abstraction
+
+Un service est un répertoire contenant `docker-compose.yaml` et `composia-meta.yaml`. Vous organisez les répertoires comme vous le souhaitez. Vous pouvez ajouter tout fichier dont un projet Compose a besoin : fichiers d'environnement, modèles de configuration, Caddyfile, scripts personnalisés.
+
+Composia lit ces fichiers depuis votre dépôt Git et construit des bundles de service que les agents exécutent avec `docker compose`. Rien n'est converti, traduit ou réécrit. Vos fichiers Compose sont la source unique de vérité.
+
+### Natif Git
+
+Le contrôleur stocke l'état désiré dans un dépôt Git. Chaque modification est un commit avec un auteur et un message. Vous obtenez l'historique des versions, la capacité de rollback et la possibilité de synchroniser avec un dépôt distant. Utilisez n'importe quel workflow Git que vous connaissez déjà.
+
+### CLI et API d'abord
+
+Tout ce que vous pouvez faire dans l'interface web, vous pouvez le faire avec la CLI `composia`. La CLI utilise la même API publique que le frontend web. Le scripting, les pipelines CI et les agents IA communiquent avec Composia via la même interface.
+
+L'interface web est une application SvelteKit qui appelle la même API du contrôleur. Il n'y a pas d'API de gestion séparée ni de points de terminaison internes.
+
+## Ce que vous obtenez
+
+**Déploiement multi-nœud.** Définissez sur quels nœuds un service doit s'exécuter dans `composia-meta.yaml`. Composia déploie le service sur tous les nœuds cibles et rapporte l'état de chacun.
+
+**Tableau de bord web.** Parcourez et modifiez les fichiers du dépôt, visualisez les logs des conteneurs en direct, inspectez les ressources Docker (conteneurs, images, réseaux, volumes) et ouvrez des terminaux interactifs dans les conteneurs en cours d'exécution. Le tableau de bord fonctionne sur mobile.
+
+**Sauvegarde et restauration.** Sauvegardes automatisées basées sur Rustic, avec exécutions planifiées, gestion des snapshots et restaurations à la demande. Protégez les fichiers, répertoires, volumes nommés et bases de données PostgreSQL.
+
+**Gestion DNS.** Création automatique d'enregistrements DNS pour Cloudflare, AliDNS, DNSPod, Route53 et Huawei Cloud. Les enregistrements sont synchronisés au déploiement et supprimés à l'arrêt.
+
+**Reverse proxy.** Intégration Caddy qui synchronise les configurations Caddyfile par service et déclenche les rechargements automatiquement. Les fichiers de configuration générés résident sur l'agent et sont importés par le service d'infrastructure Caddy.
+
+**Mises à jour d'images.** Détection automatique des nouvelles versions d'images depuis les registres Docker et les releases GitHub, GitLab ou Forgejo. Prend en charge le filtrage par semver, date, regex et latest. Appliquez les mises à jour automatiquement ou révisez-les avant application.
+
+**Notifications.** Notifications par e-mail (SMTP), Telegram et Alertmanager pour les résultats de tâches, les événements de sauvegarde, les mises à jour d'images et les changements d'état des nœuds. Filtrez par type d'événement et source de tâche.
+
+**Secrets chiffrés.** Chiffrement basé sur age pour les fichiers de secrets de service. Les secrets sont stockés chiffrés dans le dépôt et déchiffrés uniquement sur le contrôleur. Les agents reçoivent le contenu déchiffré dans les bundles de service sans jamais accéder à la clé privée.
+
+**Système de tâches.** Chaque opération est une tâche tracée avec progression par étape, sortie complète des logs et état d'achèvement. Relancez les tâches, inspectez les étapes des tâches et suivez les logs en temps réel.
+
+**Métriques Prometheus.** Le contrôleur expose des métriques Prometheus sur son serveur HTTP.
+
+## À qui il s'adresse
+
+Composia est conçu pour les utilisateurs expérimentés et les équipes d'exploitation qui :
+
+- Utilisent déjà Docker Compose et souhaitent une coordination multi-nœud sans changer leur workflow.
+- Préfèrent la configuration en texte brut dans Git plutôt que de cliquer dans un formulaire web.
+- Veulent de l'automatisation (sauvegardes, DNS, mises à jour) mais refusent de confier leurs fichiers Compose à une plateforme.
+- Ont besoin d'une CLI qu'ils peuvent scripter et intégrer, pas seulement une interface navigateur.
+- Apprécient une infrastructure sans base de données, sans dépendance propriétaire et à faibles dépendances.
diff --git a/site/content/docs/about/why-composia.ja.md b/site/content/docs/about/why-composia.ja.md
new file mode 100644
index 0000000..d976a46
--- /dev/null
+++ b/site/content/docs/about/why-composia.ja.md
@@ -0,0 +1,83 @@
+---
+title: "なぜ Composia か"
+date: '2026-05-26T00:00:00+08:00'
+weight: 10
+---
+
+Composia は Docker Compose 向けのセルフホスト型コントロールプレーンです。サービスをプレーンファイルとして定義し、1 つまたは複数のノードにデプロイし、インフラ全体を統一的に可視化します。
+
+## PaaS ではありません
+
+セルフホスト型 PaaS プラットフォームとは異なり、Composia はあなたの Compose ファイルを独自のアプリケーションモデルで置き換えたりしません。設定はあなたが所有する標準の `docker-compose.yaml` と `composia-meta.yaml` ファイルに保存されます。コントロールプレーンは調整と報告を行いますが、各ノードへの直接の CLI およびファイルベースのアクセスは常に保持されます。
+
+Composia を停止しても `docker compose` コマンドは引き続き動作します。すべての操作は標準の Docker と Compose のプリミティブの上に構築されています。ロックインはありません。
+
+## 他ツールとの比較
+
+### Dockge、Dockman
+
+Dockge と Dockman は個別の Compose スタックの管理をより快適にします。ブラウザ UI によるシングルノードの利便性に焦点を当てています。
+
+Composia はファイルファーストのアプローチを共有しつつ、マルチノード調整を追加しています。設定した任意のノードにサービスをデプロイし、すべてのサービスとノードを 1 つのダッシュボードで統一的に表示し、すべての操作を完全なログ付きで記録するタスクシステムを使用します。CLI はスクリプトと自動化のために構築されており、単なる一時的な利用ではありません。
+
+### Dokploy、Coolify
+
+Dokploy と Coolify はセルフホスト型 PaaS プラットフォームです。独自のアプリケーションモデルを定義し、ビルドパイプラインを管理し、基盤インフラを抽象化します。これらを採用すると、デプロイワークフローはその抽象化に依存することになります。
+
+Composia は逆のアプローチを取ります。既存の Compose ファイルをあなた自身のディレクトリ構造のまま扱います。ビルドパイプラインも、学習すべきアプリケーションモデルも、あなたと Docker の間の抽象化レイヤーもありません。Composia は Docker が行う作業を調整します — Docker をプラットフォームの抽象化の背後に隠したりしません。
+
+## 設計上の決定
+
+### データベースフリー
+
+Composia はランタイム状態に SQLite を、期待状態設定に Git を使用します。PostgreSQL、MySQL、外部データベース依存は一切ありません。
+
+Git リポジトリと SQLite データベースファイルをバックアップするだけで Composia 全体をバックアップできます。新しいマシンにそれらをリストアすればすぐに復旧します。データベースマイグレーションも、接続プールも、別途のデータベースサーバーも不要です。
+
+### 標準ファイル、抽象化なし
+
+サービスとは `docker-compose.yaml` と `composia-meta.yaml` を含むディレクトリです。ディレクトリの構成は自由です。Compose プロジェクトが必要とする任意のファイル（env ファイル、設定テンプレート、Caddyfile、カスタムスクリプト）を追加できます。
+
+Composia はこれらのファイルを Git リポジトリから読み取り、エージェントが `docker compose` で実行するサービスのバンドルを構築します。変換や翻訳、書き換えは一切行われません。あなたの Compose ファイルが信頼できる唯一の情報源です。
+
+### Git ネイティブ
+
+コントローラーは期待状態を Git リポジトリに保存します。すべての変更は作成者とメッセージ付きのコミットです。バージョン履歴、ロールバック機能、リモートリポジトリとの同期機能が得られます。すでに知っている Git ワークフローをそのまま使えます。
+
+### CLI と API ファースト
+
+Web UI でできることはすべて `composia` CLI でも実行できます。CLI は Web フロントエンドと同じパブリック API を使用します。スクリプト、CI パイプライン、AI エージェントは同じインターフェースを通じて Composia とやり取りします。
+
+Web UI は同じコントローラー API を呼び出す SvelteKit アプリケーションです。別途の管理 API や内部専用エンドポイントはありません。
+
+## 提供される機能
+
+**マルチノードデプロイ。** `composia-meta.yaml` でサービスを実行するノードを定義します。Composia はすべてのターゲットノードにサービスをデプロイし、各ノードのステータスを報告します。
+
+**Web ダッシュボード。** リポジトリファイルの閲覧と編集、コンテナのライブログ表示、Docker リソース（コンテナ、イメージ、ネットワーク、ボリューム）の検査、実行中のコンテナへのインタラクティブターミナル。モバイルでも動作します。
+
+**バックアップとリストア。** Rustic による自動バックアップ。スケジュール実行、スナップショット管理、オンデマンドリストア。ファイル、ディレクトリ、名前付きボリューム、PostgreSQL データベースを保護します。
+
+**DNS 管理。** Cloudflare、AliDNS、DNSPod、Route53、Huawei Cloud 向けの自動 DNS レコード作成。レコードはデプロイ時に同期され、停止時に削除されます。
+
+**リバースプロキシ。** サービスごとの Caddyfile 設定を同期し、自動的にリロードをトリガーする Caddy 統合。生成された設定ファイルはエージェント上に存在し、Caddy インフラストラクチャサービスによってインポートされます。
+
+**イメージ更新。** Docker レジストリや GitHub、GitLab、Forgejo のリリースから新しいイメージバージョンを自動検出。semver、日付、正規表現、latest フィルタリングをサポート。更新を自動適用または確認後に適用します。
+
+**通知。** タスク結果、バックアップイベント、イメージ更新、ノード状態変化を Email（SMTP）、Telegram、Alertmanager で通知。イベントタイプとタスクソースによるフィルタリングが可能です。
+
+**暗号化シークレット。** サービスのシークレットファイルに Age ベースの暗号化。シークレットはリポジトリに暗号化された状態で保存され、コントローラー上でのみ復号されます。エージェントは秘密鍵にアクセスすることなく、サービスバンドル内で復号されたコンテンツを受け取ります。
+
+**タスクシステム。** すべての操作はステップレベルの進捗、完全なログ出力、完了ステータスを持つ追跡可能なタスクです。タスクの再実行、タスクステップの検査、リアルタイムのログ追跡が可能です。
+
+**Prometheus メトリクス。** コントローラーは HTTP サーバー上で Prometheus メトリクスを公開します。
+
+## 対象ユーザー
+
+Composia は以下のようなパワーユーザーと運用チームのために作られています:
+
+- すでに Docker Compose を使用しており、ワークフローを変えずにマルチノード調整を求めている方。
+- Web フォームをクリックするよりも Git でのプレーンテキスト設定を好む方。
+- 自動化（バックアップ、DNS、更新）を求めつつも、Compose ファイルをプラットフォームに委ねることを拒否する方。
+- ブラウザ UI だけでなく、スクリプト化・統合可能な CLI を必要とする方。
+- データベースフリー、ロックインフリー、低依存のインフラを重視する方。
diff --git a/site/content/docs/about/why-composia.zh-hans.md b/site/content/docs/about/why-composia.zh-hans.md
new file mode 100644
index 0000000..42a4e88
--- /dev/null
+++ b/site/content/docs/about/why-composia.zh-hans.md
@@ -0,0 +1,83 @@
+---
+title: "为什么选择 Composia"
+date: '2026-05-26T00:00:00+08:00'
+weight: 10
+---
+
+Composia 是一个自托管的 Docker Compose 控制平面。将服务定义为纯文本文件，部署到一个或多个节点，并在整个基础设施中获得统一的可见性。
+
+## 它不是一个 PaaS
+
+与自托管 PaaS 平台不同，Composia 不会用自己的应用模型替换您的 Compose 文件。您的配置存放在标准的 `docker-compose.yaml` 和 `composia-meta.yaml` 文件中，由您掌控。控制平面负责协调和上报，但您始终保留对每个节点的直接 CLI 和基于文件的访问权限。
+
+关闭 Composia，您的 `docker compose` 命令仍然有效。所有操作都建立在标准的 Docker 和 Compose 原语之上。不存在平台绑定。
+
+## 与其他工具对比
+
+### Dockge、Dockman
+
+Dockge 和 Dockman 让管理单个 Compose 堆栈更加方便。它们侧重于单节点的便捷性，提供浏览器 UI。
+
+Composia 同样采用文件优先的方式，但增加了多节点协调功能：将服务部署到任意已配置的节点，在一个仪表盘中统一查看所有服务和节点，并使用记录了每次操作和完整日志的任务系统。CLI 专为脚本编写和自动化而设计，而非偶尔使用。
+
+### Dokploy、Coolify
+
+Dokploy 和 Coolify 是自托管 PaaS 平台。它们定义了自己的应用模型，管理构建流水线，并抽象了底层基础设施。一旦采用它们，您的部署流程就依赖于它们的抽象层。
+
+Composia 则采取相反的方式。它直接使用您现有的 Compose 文件和目录结构。没有构建流水线，无需学习新的应用模型，在您和 Docker 之间没有任何抽象层。Composia 协调 Docker 的工作——它不会将 Docker 隐藏在平台抽象之后。
+
+## 设计决策
+
+### 无需数据库
+
+Composia 使用 SQLite 存储运行时状态，使用 Git 存储期望状态配置。没有 PostgreSQL、MySQL 或任何外部数据库依赖。
+
+备份整个 Composia 安装只需备份您的 Git 仓库和 SQLite 数据库文件。在新机器上恢复这些文件即可重新上线。无需数据库迁移、连接池或单独的数据库服务器。
+
+### 标准文件，无抽象层
+
+一个服务就是一个包含 `docker-compose.yaml` 和 `composia-meta.yaml` 的目录。目录结构由您自由组织。您可以添加 Compose 项目所需的任何文件：环境变量文件、配置模板、Caddyfile、自定义脚本等。
+
+Composia 从 Git 仓库读取这些文件并构建服务包，由 agent 执行 `docker compose` 命令。没有任何转换、翻译或重写。您的 Compose 文件是唯一的数据源。
+
+### Git 原生
+
+控制器将期望状态存储在 Git 仓库中。每次变更都是一次带作者和消息的提交。您可以获得版本历史、回滚能力以及同步到远程仓库的能力。使用您已经熟悉的任何 Git 工作流程。
+
+### CLI 与 API 优先
+
+您在 Web UI 中能做的所有操作，都可以通过 `composia` CLI 完成。CLI 使用与 Web 前端相同的公共 API。脚本、CI 流水线和 AI 智能体通过同一个接口与 Composia 通信。
+
+Web UI 是一个 SvelteKit 应用，调用的是同一个控制器 API。没有单独的管理 API 或内部专用端点。
+
+## 您能获得什么
+
+**多节点部署。** 在 `composia-meta.yaml` 中定义服务应运行在哪些节点上。Composia 将服务部署到所有目标节点，并报告每个节点的状态。
+
+**Web 仪表盘。** 浏览和编辑仓库文件、查看实时容器日志、检查 Docker 资源（容器、镜像、网络、卷），以及打开交互式终端进入运行中的容器。仪表盘支持移动端。
+
+**备份与恢复。** 由 Rustic 驱动的自动备份，支持定时运行、快照管理和按需恢复。保护文件、目录、命名卷和 PostgreSQL 数据库。
+
+**DNS 管理。** 自动为 Cloudflare、AliDNS、DNSPod、Route53 和华为云创建 DNS 记录。记录在部署时同步，在停止时移除。
+
+**反向代理。** Caddy 集成，同步每个服务的 Caddyfile 配置并自动触发重载。生成的配置文件存放在 agent 上，由 Caddy 基础设施服务导入。
+
+**镜像更新。** 自动检测 Docker 注册表以及 GitHub、GitLab 或 Forgejo 发布的新镜像版本。支持语义化版本、日期、正则表达式和最新版本过滤。可以自动应用更新，也可在应用前进行审核。
+
+**通知。** 邮件（SMTP）、Telegram 和 Alertmanager 通知，覆盖任务结果、备份事件、镜像更新和节点状态变化。可按事件类型和任务来源过滤。
+
+**加密密钥。** 基于 age 加密的服务密钥文件。密钥以加密形式存储在仓库中，仅在控制器上解密。Agent 在服务包中接收解密后的内容，但无法访问私钥。
+
+**任务系统。** 每个操作都是一个被追踪的任务，包含步骤级进度、完整日志输出和完成状态。可重新运行任务、检查任务步骤并实时查看日志。
+
+**Prometheus 指标。** 控制器在其 HTTP 服务器上暴露 Prometheus 指标。
+
+## 适用人群
+
+Composia 为进阶用户和运维团队打造，适合以下人群：
+
+- 已经在使用 Docker Compose，并希望在不改变工作流程的情况下获得多节点协调能力。
+- 更倾向于在 Git 中管理纯文本配置，而不是通过 web 表单点击操作。
+- 需要自动化（备份、DNS、更新）但拒绝将 Compose 文件交给某个平台。
+- 需要一个可以编写脚本和集成的 CLI，而不仅仅是浏览器 UI。
+- 重视无数据库、无平台绑定、低依赖的基础设施。
diff --git a/site/content/docs/about/why-composia.zh-hant.md b/site/content/docs/about/why-composia.zh-hant.md
new file mode 100644
index 0000000..62ace9e
--- /dev/null
+++ b/site/content/docs/about/why-composia.zh-hant.md
@@ -0,0 +1,83 @@
+---
+title: "為什麼選擇 Composia"
+date: '2026-05-26T00:00:00+08:00'
+weight: 10
+---
+
+Composia 是一個自託管的 Docker Compose 控制平面。將您的服務定義為純文字檔案，部署到一個或多個節點，並在整個基礎架構中獲得統一的可見性。
+
+## 它不是 PaaS
+
+與自託管的 PaaS 平台不同，Composia 不會用自身的應用程式模型取代您的 Compose 檔案。您的設定檔存放在標準的 `docker-compose.yaml` 和 `composia-meta.yaml` 檔案中，完全由您掌控。控制平面負責協調與回報，但您始終保有對每個節點的直接 CLI 與檔案層級存取。
+
+關閉 Composia 後，您的 `docker compose` 指令仍然可以運作。每個操作都建立在標準的 Docker 與 Compose 基本元件之上。完全沒有鎖定風險。
+
+## 與其他工具的比較
+
+### Dockge、Dockman
+
+Dockge 與 Dockman 讓管理個別 Compose 堆疊更加便利，專注於單節點操作並提供瀏覽器 UI。
+
+Composia 同樣採取檔案優先的設計，但增加了多節點協調能力：將服務部署到任意已設定的節點，在單一儀表板中檢視所有服務與節點的統一狀態，並使用任務系統記錄每個操作及完整日誌。CLI 專為腳本編寫與自動化而設計，而非僅供偶爾使用。
+
+### Dokploy、Coolify
+
+Dokploy 與 Coolify 是自託管的 PaaS 平台。它們定義自己的應用程式模型、管理建置管線，並將底層基礎架構抽象化。一旦採用它們，您的部署工作流程就會依賴於它們的抽象層。
+
+Composia 採取相反的做法。它直接使用您現有的 Compose 檔案和您自己的目錄結構。沒有建置管線、沒有需要學習的應用程式模型、您與 Docker 之間沒有抽象層。Composia 協調 Docker 執行的工作——它不會將 Docker 隱藏在平台抽象層之後。
+
+## 設計決策
+
+### 無資料庫
+
+Composia 使用 SQLite 儲存執行時期狀態，並使用 Git 儲存期望狀態設定。不需要 PostgreSQL、MySQL 或任何外部資料庫依賴。
+
+備份整個 Composia 安裝只需備份您的 Git 存放庫和 SQLite 資料庫檔案。將它們還原到新機器即可恢復上線。無需資料庫遷移、無連線池、無獨立的資料庫伺服器。
+
+### 標準檔案，無抽象層
+
+一個服務就是一個包含 `docker-compose.yaml` 和 `composia-meta.yaml` 的目錄。您可以按自己的方式組織目錄，也可以加入 Compose 專案所需的任何檔案：env 檔案、設定範本、Caddyfile、自訂腳本。
+
+Composia 從您的 Git 存放庫讀取這些檔案，並建置服務包供代理使用 `docker compose` 執行。沒有任何轉換、翻譯或重寫。您的 Compose 檔案就是唯一的真實來源。
+
+### Git 原生
+
+控制器將期望狀態存放在 Git 存放庫中。每次變更都是一個帶有作者與訊息的提交。您獲得版本歷史、回溯能力，以及與遠端存放庫同步的能力。使用您已熟悉的任何 Git 工作流程。
+
+### CLI 與 API 優先
+
+在 Web UI 中能做的所有事，都可以透過 `composia` CLI 完成。CLI 使用與 Web 前端相同的公開 API。腳本、CI 管線與 AI 代理都透過同一個介面與 Composia 溝通。
+
+Web UI 是一個呼叫相同控制器 API 的 SvelteKit 應用程式。沒有獨立的管理 API 或內部專用端點。
+
+## 您所獲得的
+
+**多節點部署。** 在 `composia-meta.yaml` 中定義服務應在哪些節點上執行。Composia 將服務部署到所有目標節點並回報每個節點的狀態。
+
+**Web 儀表板。** 瀏覽與編輯存放庫檔案、檢視即時容器日誌、檢查 Docker 資源（容器、映像檔、網路、磁碟區），並開啟執行中容器的互動式終端機。儀表板支援行動裝置。
+
+**備份與還原。** 由 Rustic 驅動的自動化備份，支援排程執行、快照管理與隨需還原。保護檔案、目錄、具名磁碟區與 PostgreSQL 資料庫。
+
+**DNS 管理。** 自動為 Cloudflare、AliDNS、DNSPod、Route53 與華為雲建立 DNS 記錄。在部署時同步記錄，並在停止時移除。
+
+**反向代理。** Caddy 整合，同步各服務的 Caddyfile 設定並自動觸發重新載入。產生的設定檔存放在代理端，由 Caddy 基礎架構服務匯入。
+
+**映像檔更新。** 自動從 Docker 登錄庫與 GitHub、GitLab 或 Forgejo 發行版本中偵測新的映像檔版本。支援 semver、日期、正則表達式和 latest 過濾。可自動套用更新或先審查再套用。
+
+**通知。** Email (SMTP)、Telegram 與 Alertmanager 通知，涵蓋任務結果、備份事件、映像檔更新與節點狀態變更。可按事件類型與任務來源過濾。
+
+**加密密鑰。** 使用 Age 加密服務密鑰檔案。密鑰以加密形式存放在存放庫中，僅在控制器端解密。代理在服務包中收到解密內容，從不接觸私鑰。
+
+**任務系統。** 每個操作都是一個可追蹤的任務，包含步驟層級的進度、完整日誌輸出與完成狀態。可重新執行任務、檢查任務步驟並即時追蹤日誌。
+
+**Prometheus 指標。** 控制器在其 HTTP 伺服器上提供 Prometheus 指標。
+
+## 適合的使用者
+
+Composia 為進階使用者和運維團隊打造，適合以下人群：
+
+- 已在使用 Docker Compose，希望增加多節點協調但不改變現有工作流程。
+- 偏好 Git 中的純文字設定，而非透過網頁表單點擊操作。
+- 需要自動化（備份、DNS、更新），但不願將 Compose 檔案交給平台。
+- 需要可編寫腳本與整合的 CLI，而不僅僅是瀏覽器 UI。
+- 重視無資料庫、無鎖定與低依賴的基礎架構。
diff --git a/site/content/docs/client/_index.de.md b/site/content/docs/client/_index.de.md
new file mode 100644
index 0000000..1e37729
--- /dev/null
+++ b/site/content/docs/client/_index.de.md
@@ -0,0 +1,12 @@
+---
+title: "Client"
+date: '2026-05-26T00:00:00+08:00'
+weight: 20
+---
+
+Wege, mit Composia zu interagieren:
+
+- **Web-UI** — browserbasiertes Dashboard zur Verwaltung von Diensten, Nodes, Aufgaben, Backups und Einstellungen. Öffne `http://localhost:3000` nach dem Start des Stacks.
+- **CLI** — `composia`-Kommandozeilenwerkzeug für Skripting und Terminal-Workflows. Installiere über [Paketmanager](/docs/installation/package-managers/) oder lade es von der [Releases-Seite](https://forgejo.alexma.top/alexma233/composia/releases) herunter.
+
+Sowohl die Web-UI als auch die CLI kommunizieren mit derselben [Controller-API](/docs/developer-guide/api/).
diff --git a/site/content/docs/client/_index.fr.md b/site/content/docs/client/_index.fr.md
new file mode 100644
index 0000000..aa941aa
--- /dev/null
+++ b/site/content/docs/client/_index.fr.md
@@ -0,0 +1,12 @@
+---
+title: "Client"
+date: '2026-05-26T00:00:00+08:00'
+weight: 20
+---
+
+Façons d'interagir avec Composia :
+
+- **Interface web** — tableau de bord dans le navigateur pour gérer les services, les nœuds, les tâches, les sauvegardes et les paramètres. Ouvrez `http://localhost:3000` après avoir démarré la pile.
+- **CLI** — outil en ligne de commande `composia` pour le scripting et les workflows en terminal. Installez via les [gestionnaires de paquets](/docs/installation/package-managers/) ou téléchargez depuis la [page des releases](https://forgejo.alexma.top/alexma233/composia/releases).
+
+L'interface web et la CLI communiquent toutes deux avec la même [API du contrôleur](/docs/developer-guide/api/).
diff --git a/site/content/docs/client/_index.ja.md b/site/content/docs/client/_index.ja.md
new file mode 100644
index 0000000..d57005f
--- /dev/null
+++ b/site/content/docs/client/_index.ja.md
@@ -0,0 +1,12 @@
+---
+title: "クライアント"
+date: '2026-05-26T00:00:00+08:00'
+weight: 20
+---
+
+Composia と対話する方法:
+
+- **Web UI** — サービス、ノード、タスク、バックアップ、設定を管理するブラウザベースのダッシュボード。スタック起動後に `http://localhost:3000` を開きます。
+- **CLI** — スクリプトとターミナルワークフローのための `composia` コマンドラインツール。[パッケージマネージャー](/docs/installation/package-managers/) 経由でインストールするか、[リリースページ](https://forgejo.alexma.top/alexma233/composia/releases) からダウンロードします。
+
+Web UI と CLI はどちらも同じ [コントローラー API](/docs/developer-guide/api/) と通信します。
diff --git a/site/content/docs/client/_index.zh-hans.md b/site/content/docs/client/_index.zh-hans.md
new file mode 100644
index 0000000..2991ac0
--- /dev/null
+++ b/site/content/docs/client/_index.zh-hans.md
@@ -0,0 +1,12 @@
+---
+title: "客户端"
+date: '2026-05-26T00:00:00+08:00'
+weight: 20
+---
+
+与 Composia 交互的方式：
+
+- **Web UI** — 基于浏览器的仪表盘，用于管理服务、节点、任务、备份和设置。启动堆栈后访问 `http://localhost:3000`。
+- **CLI** — `composia` 命令行工具，用于脚本编写和终端工作流。通过[包管理器](/docs/installation/package-managers/)安装或从[发布页面](https://forgejo.alexma.top/alexma233/composia/releases)下载。
+
+Web UI 和 CLI 都与同一个[控制器 API](/docs/developer-guide/api/) 通信。
diff --git a/site/content/docs/client/_index.zh-hant.md b/site/content/docs/client/_index.zh-hant.md
new file mode 100644
index 0000000..b8830d5
--- /dev/null
+++ b/site/content/docs/client/_index.zh-hant.md
@@ -0,0 +1,12 @@
+---
+title: "客戶端"
+date: '2026-05-26T00:00:00+08:00'
+weight: 20
+---
+
+與 Composia 互動的方式：
+
+- **Web UI** — 基於瀏覽器的儀表板，用於管理服務、節點、任務、備份與設定。啟動堆疊後開啟 `http://localhost:3000`。
+- **CLI** — `composia` 命令列工具，用於腳本編寫與終端機工作流程。可透過[套件管理器](/docs/installation/package-managers/)安裝，或從[發行版本頁面](https://forgejo.alexma.top/alexma233/composia/releases)下載。
+
+Web UI 與 CLI 都與相同的[控制器 API](/docs/developer-guide/api/) 溝通。
diff --git a/site/content/docs/developer-guide/_index.de.md b/site/content/docs/developer-guide/_index.de.md
new file mode 100644
index 0000000..664c823
--- /dev/null
+++ b/site/content/docs/developer-guide/_index.de.md
@@ -0,0 +1,10 @@
+---
+title: "Entwickler-Leitfaden"
+date: '2026-05-26T00:00:00+08:00'
+weight: 40
+---
+
+Ressourcen, um zu Composia beizutragen oder Integrationen zu erstellen:
+
+- [Source Build](source-build/) — Binärdateien und lokale Container-Images aus dem Quellcode bauen.
+- [API-Referenz](api/) — automatisch aus Protobuf-Definitionen generiert.
diff --git a/site/content/docs/developer-guide/_index.fr.md b/site/content/docs/developer-guide/_index.fr.md
new file mode 100644
index 0000000..9858d93
--- /dev/null
+++ b/site/content/docs/developer-guide/_index.fr.md
@@ -0,0 +1,10 @@
+---
+title: "Guide développeur"
+date: '2026-05-26T00:00:00+08:00'
+weight: 40
+---
+
+Ressources pour contribuer à Composia ou créer des intégrations :
+
+- [Build depuis les sources](source-build/) — compiler les binaires et les images de conteneur locales depuis les sources.
+- [Référence API](api/) — générée automatiquement à partir des définitions protobuf.
diff --git a/site/content/docs/developer-guide/_index.ja.md b/site/content/docs/developer-guide/_index.ja.md
new file mode 100644
index 0000000..e35ccc1
--- /dev/null
+++ b/site/content/docs/developer-guide/_index.ja.md
@@ -0,0 +1,10 @@
+---
+title: "開発者ガイド"
+date: '2026-05-26T00:00:00+08:00'
+weight: 40
+---
+
+Composia への貢献や統合の構築のためのリソース:
+
+- [ソースビルド](source-build/) - ソースからバイナリとローカルコンテナイメージをビルドします。
+- [API リファレンス](api/) - protobuf 定義から自動生成されます。
diff --git a/site/content/docs/developer-guide/_index.zh-hans.md b/site/content/docs/developer-guide/_index.zh-hans.md
new file mode 100644
index 0000000..c64f067
--- /dev/null
+++ b/site/content/docs/developer-guide/_index.zh-hans.md
@@ -0,0 +1,10 @@
+---
+title: "开发者指南"
+date: '2026-05-26T00:00:00+08:00'
+weight: 40
+---
+
+为贡献 Composia 或构建集成的资源：
+
+- [源码构建](source-build/) - 从源码构建二进制文件和本地容器镜像。
+- [API 参考](api/) - 从 protobuf 定义自动生成。
diff --git a/site/content/docs/developer-guide/_index.zh-hant.md b/site/content/docs/developer-guide/_index.zh-hant.md
new file mode 100644
index 0000000..1421c86
--- /dev/null
+++ b/site/content/docs/developer-guide/_index.zh-hant.md
@@ -0,0 +1,10 @@
+---
+title: "開發者指南"
+date: '2026-05-26T00:00:00+08:00'
+weight: 40
+---
+
+貢獻 Composia 或建置整合的資源：
+
+- [原始碼建置](source-build/) - 從原始碼建置二進位檔與本地容器映像檔。
+- [API 參考](api/) - 從 protobuf 定義自動產生。
diff --git a/site/content/docs/developer-guide/source-build.de.md b/site/content/docs/developer-guide/source-build.de.md
new file mode 100644
index 0000000..fed3d24
--- /dev/null
+++ b/site/content/docs/developer-guide/source-build.de.md
@@ -0,0 +1,75 @@
+---
+title: "Source Build"
+date: '2026-05-26T00:00:00+08:00'
+weight: 20
+---
+
+Baue aus dem Quellcode, wenn du benutzerdefinierte Patches, Entwicklungs-Binärdateien oder Paketierungsarbeiten benötigst.
+
+## Voraussetzungen
+
+- Go, wie in `mise.toml` und `go.mod` deklariert.
+- Git, für Versionierung und Repository-Operationen.
+
+Verwende `mise`, um die Projekt-Toolchain zu installieren:
+
+```bash
+mise install
+```
+
+## Bauen mit dem Skript
+
+Das Build-Skript schreibt die Ausgabe nach `dist/_/` und generiert Prüfsummen, wenn `sha256sum` verfügbar ist:
+
+```bash
+sh scripts/build/binaries.sh
+```
+
+Unter Linux baut es:
+
+- `composia`
+- `composia-controller`
+- `composia-agent`
+
+Unter macOS und Windows baut es nur die CLI.
+
+## Build-Variablen
+
+| Variable | Standard | Zweck |
+|----------|---------|---------|
+| `VERSION` | `git describe --tags --always --dirty` | In Binärdateien eingebettete Version. |
+| `OUTPUT_DIR` | `dist` | Ausgabeverzeichnis. |
+| `GOOS` | Host-Betriebssystem | Ziel-Betriebssystem. |
+| `GOARCH` | Host-Architektur | Ziel-Architektur. |
+| `GOARM` | Leer | ARM-Variante, z.B. `7`. |
+| `CGO_ENABLED` | `0` | Statische Cross-Builds. |
+
+Beispiele:
+
+```bash
+GOOS=linux GOARCH=arm64 sh scripts/build/binaries.sh
+GOOS=linux GOARCH=arm GOARM=7 sh scripts/build/binaries.sh
+```
+
+## Manueller Go-Build
+
+```bash
+LDFLAGS="-s -w -X forgejo.alexma.top/alexma233/composia/internal/version.Value=$(git describe --tags --always --dirty)"
+
+CGO_ENABLED=0 go build -trimpath -ldflags "$LDFLAGS" -o composia ./cmd/composia
+CGO_ENABLED=0 go build -trimpath -ldflags "$LDFLAGS" -o composia-controller ./cmd/composia-controller
+CGO_ENABLED=0 go build -trimpath -ldflags "$LDFLAGS" -o composia-agent ./cmd/composia-agent
+```
+
+## Container-Images bauen
+
+Das `Dockerfile` im Wurzelverzeichnis hat Ziele für jede Laufzeitumgebung:
+
+```bash
+docker build --target cli -t composia-cli:local .
+docker build --target controller -t composia-controller:local .
+docker build --target agent -t composia-agent:local .
+docker build --target dev -t composia-dev:local .
+```
+
+Das `dev`-Image enthält Go, Air, Docker CLI, Docker Buildx, Docker Compose und Git.
diff --git a/site/content/docs/developer-guide/source-build.fr.md b/site/content/docs/developer-guide/source-build.fr.md
new file mode 100644
index 0000000..6a2de83
--- /dev/null
+++ b/site/content/docs/developer-guide/source-build.fr.md
@@ -0,0 +1,75 @@
+---
+title: "Build depuis les sources"
+date: '2026-05-26T00:00:00+08:00'
+weight: 20
+---
+
+Compilez depuis les sources lorsque vous avez besoin de correctifs personnalisés, de binaires de développement ou de travaux de packaging.
+
+## Prérequis
+
+- Go, tel que déclaré dans `mise.toml` et `go.mod`.
+- Git, pour le versionnement et les opérations sur le dépôt.
+
+Utilisez `mise` pour installer la chaîne d'outils du projet :
+
+```bash
+mise install
+```
+
+## Compiler avec le script
+
+Le script de build écrit la sortie dans `dist/_/` et génère des sommes de contrôle lorsque `sha256sum` est disponible :
+
+```bash
+sh scripts/build/binaries.sh
+```
+
+Sur Linux, il compile :
+
+- `composia`
+- `composia-controller`
+- `composia-agent`
+
+Sur macOS et Windows, il compile uniquement la CLI.
+
+## Variables de build
+
+| Variable | Valeur par défaut | Rôle |
+|----------|---------|---------|
+| `VERSION` | `git describe --tags --always --dirty` | Version intégrée dans les binaires. |
+| `OUTPUT_DIR` | `dist` | Répertoire de sortie. |
+| `GOOS` | OS hôte | OS cible. |
+| `GOARCH` | Architecture hôte | Architecture cible. |
+| `GOARM` | Vide | Variante ARM, comme `7`. |
+| `CGO_ENABLED` | `0` | Compilations croisées statiques. |
+
+Exemples :
+
+```bash
+GOOS=linux GOARCH=arm64 sh scripts/build/binaries.sh
+GOOS=linux GOARCH=arm GOARM=7 sh scripts/build/binaries.sh
+```
+
+## Build Go manuel
+
+```bash
+LDFLAGS="-s -w -X forgejo.alexma.top/alexma233/composia/internal/version.Value=$(git describe --tags --always --dirty)"
+
+CGO_ENABLED=0 go build -trimpath -ldflags "$LDFLAGS" -o composia ./cmd/composia
+CGO_ENABLED=0 go build -trimpath -ldflags "$LDFLAGS" -o composia-controller ./cmd/composia-controller
+CGO_ENABLED=0 go build -trimpath -ldflags "$LDFLAGS" -o composia-agent ./cmd/composia-agent
+```
+
+## Build des images de conteneur
+
+Le `Dockerfile` racine a des cibles pour chaque runtime :
+
+```bash
+docker build --target cli -t composia-cli:local .
+docker build --target controller -t composia-controller:local .
+docker build --target agent -t composia-agent:local .
+docker build --target dev -t composia-dev:local .
+```
+
+L'image `dev` inclut Go, Air, Docker CLI, Docker Buildx, Docker Compose et Git.
diff --git a/site/content/docs/developer-guide/source-build.ja.md b/site/content/docs/developer-guide/source-build.ja.md
new file mode 100644
index 0000000..4b800f9
--- /dev/null
+++ b/site/content/docs/developer-guide/source-build.ja.md
@@ -0,0 +1,75 @@
+---
+title: "ソースビルド"
+date: '2026-05-26T00:00:00+08:00'
+weight: 20
+---
+
+カスタムパッチ、開発用バイナリ、パッケージング作業が必要な場合はソースからビルドします。
+
+## 前提条件
+
+- `mise.toml` と `go.mod` で宣言されているバージョンの Go。
+- バージョンスタンプとリポジトリ操作用の Git。
+
+プロジェクトツールチェーンのインストールには `mise` を使用します:
+
+```bash
+mise install
+```
+
+## スクリプトでのビルド
+
+ビルドスクリプトは出力を `dist/_/` に書き込み、`sha256sum` が利用可能な場合はチェックサムを生成します:
+
+```bash
+sh scripts/build/binaries.sh
+```
+
+Linux では以下をビルドします:
+
+- `composia`
+- `composia-controller`
+- `composia-agent`
+
+macOS と Windows では CLI のみをビルドします。
+
+## ビルド変数
+
+| 変数 | デフォルト | 目的 |
+|----------|---------|---------|
+| `VERSION` | `git describe --tags --always --dirty` | バイナリに埋め込まれるバージョン。 |
+| `OUTPUT_DIR` | `dist` | 出力ディレクトリ。 |
+| `GOOS` | ホスト OS | ターゲット OS。 |
+| `GOARCH` | ホストアーキテクチャ | ターゲットアーキテクチャ。 |
+| `GOARM` | 空 | ARM バリアント（例: `7`）。 |
+| `CGO_ENABLED` | `0` | 静的クロスビルド。 |
+
+例:
+
+```bash
+GOOS=linux GOARCH=arm64 sh scripts/build/binaries.sh
+GOOS=linux GOARCH=arm GOARM=7 sh scripts/build/binaries.sh
+```
+
+## 手動 Go ビルド
+
+```bash
+LDFLAGS="-s -w -X forgejo.alexma.top/alexma233/composia/internal/version.Value=$(git describe --tags --always --dirty)"
+
+CGO_ENABLED=0 go build -trimpath -ldflags "$LDFLAGS" -o composia ./cmd/composia
+CGO_ENABLED=0 go build -trimpath -ldflags "$LDFLAGS" -o composia-controller ./cmd/composia-controller
+CGO_ENABLED=0 go build -trimpath -ldflags "$LDFLAGS" -o composia-agent ./cmd/composia-agent
+```
+
+## コンテナイメージのビルド
+
+ルートの `Dockerfile` には各ランタイム向けのターゲットがあります:
+
+```bash
+docker build --target cli -t composia-cli:local .
+docker build --target controller -t composia-controller:local .
+docker build --target agent -t composia-agent:local .
+docker build --target dev -t composia-dev:local .
+```
+
+`dev` イメージには Go、Air、Docker CLI、Docker Buildx、Docker Compose、Git が含まれています。
diff --git a/site/content/docs/developer-guide/source-build.zh-hans.md b/site/content/docs/developer-guide/source-build.zh-hans.md
new file mode 100644
index 0000000..4208536
--- /dev/null
+++ b/site/content/docs/developer-guide/source-build.zh-hans.md
@@ -0,0 +1,75 @@
+---
+title: "源码构建"
+date: '2026-05-26T00:00:00+08:00'
+weight: 20
+---
+
+当需要自定义补丁、开发版二进制文件或打包工作时，从源码构建。
+
+## 前置条件
+
+- Go，版本要求见 `mise.toml` 和 `go.mod`。
+- Git，用于版本标记和仓库操作。
+
+使用 `mise` 安装项目工具链：
+
+```bash
+mise install
+```
+
+## 使用构建脚本
+
+构建脚本将输出写入 `dist/_/`，并在 `sha256sum` 可用时生成校验和：
+
+```bash
+sh scripts/build/binaries.sh
+```
+
+在 Linux 上构建：
+
+- `composia`
+- `composia-controller`
+- `composia-agent`
+
+在 macOS 和 Windows 上仅构建 CLI。
+
+## 构建变量
+
+| 变量 | 默认值 | 用途 |
+|----------|---------|---------|
+| `VERSION` | `git describe --tags --always --dirty` | 嵌入到二进制文件中的版本号。 |
+| `OUTPUT_DIR` | `dist` | 输出目录。 |
+| `GOOS` | 主机 OS | 目标 OS。 |
+| `GOARCH` | 主机架构 | 目标架构。 |
+| `GOARM` | 空 | ARM 变体，如 `7`。 |
+| `CGO_ENABLED` | `0` | 静态交叉编译。 |
+
+示例：
+
+```bash
+GOOS=linux GOARCH=arm64 sh scripts/build/binaries.sh
+GOOS=linux GOARCH=arm GOARM=7 sh scripts/build/binaries.sh
+```
+
+## 手动 Go 构建
+
+```bash
+LDFLAGS="-s -w -X forgejo.alexma.top/alexma233/composia/internal/version.Value=$(git describe --tags --always --dirty)"
+
+CGO_ENABLED=0 go build -trimpath -ldflags "$LDFLAGS" -o composia ./cmd/composia
+CGO_ENABLED=0 go build -trimpath -ldflags "$LDFLAGS" -o composia-controller ./cmd/composia-controller
+CGO_ENABLED=0 go build -trimpath -ldflags "$LDFLAGS" -o composia-agent ./cmd/composia-agent
+```
+
+## 构建容器镜像
+
+根目录的 `Dockerfile` 包含每个运行时的构建目标：
+
+```bash
+docker build --target cli -t composia-cli:local .
+docker build --target controller -t composia-controller:local .
+docker build --target agent -t composia-agent:local .
+docker build --target dev -t composia-dev:local .
+```
+
+`dev` 镜像包含 Go、Air、Docker CLI、Docker Buildx、Docker Compose 和 Git。
diff --git a/site/content/docs/developer-guide/source-build.zh-hant.md b/site/content/docs/developer-guide/source-build.zh-hant.md
new file mode 100644
index 0000000..92511e4
--- /dev/null
+++ b/site/content/docs/developer-guide/source-build.zh-hant.md
@@ -0,0 +1,75 @@
+---
+title: "原始碼建置"
+date: '2026-05-26T00:00:00+08:00'
+weight: 20
+---
+
+當您需要自訂修補、開發用二進位檔或打包作業時，從原始碼建置。
+
+## 前置需求
+
+- Go，版本如 `mise.toml` 和 `go.mod` 中所宣告。
+- Git，用於版本戳記與存放庫操作。
+
+使用 `mise` 安裝專案工具鏈：
+
+```bash
+mise install
+```
+
+## 使用腳本建置
+
+建置腳本將輸出寫入 `dist/_/`，並在 `sha256sum` 可用時產生校驗碼：
+
+```bash
+sh scripts/build/binaries.sh
+```
+
+在 Linux 上會建置：
+
+- `composia`
+- `composia-controller`
+- `composia-agent`
+
+在 macOS 和 Windows 上僅建置 CLI。
+
+## 建置變數
+
+| 變數 | 預設值 | 用途 |
+|----------|---------|---------|
+| `VERSION` | `git describe --tags --always --dirty` | 嵌入二進位檔的版本。 |
+| `OUTPUT_DIR` | `dist` | 輸出目錄。 |
+| `GOOS` | 主機 OS | 目標 OS。 |
+| `GOARCH` | 主機架構 | 目標架構。 |
+| `GOARM` | 空白 | ARM 變體，如 `7`。 |
+| `CGO_ENABLED` | `0` | 靜態跨平台建置。 |
+
+範例：
+
+```bash
+GOOS=linux GOARCH=arm64 sh scripts/build/binaries.sh
+GOOS=linux GOARCH=arm GOARM=7 sh scripts/build/binaries.sh
+```
+
+## 手動 Go 建置
+
+```bash
+LDFLAGS="-s -w -X forgejo.alexma.top/alexma233/composia/internal/version.Value=$(git describe --tags --always --dirty)"
+
+CGO_ENABLED=0 go build -trimpath -ldflags "$LDFLAGS" -o composia ./cmd/composia
+CGO_ENABLED=0 go build -trimpath -ldflags "$LDFLAGS" -o composia-controller ./cmd/composia-controller
+CGO_ENABLED=0 go build -trimpath -ldflags "$LDFLAGS" -o composia-agent ./cmd/composia-agent
+```
+
+## 建置容器映像檔
+
+根目錄的 `Dockerfile` 為每個執行時期設有建置目標：
+
+```bash
+docker build --target cli -t composia-cli:local .
+docker build --target controller -t composia-controller:local .
+docker build --target agent -t composia-agent:local .
+docker build --target dev -t composia-dev:local .
+```
+
+`dev` 映像檔包含 Go、Air、Docker CLI、Docker Buildx、Docker Compose 與 Git。
diff --git a/site/content/docs/guide/_index.de.md b/site/content/docs/guide/_index.de.md
new file mode 100644
index 0000000..8ae45a4
--- /dev/null
+++ b/site/content/docs/guide/_index.de.md
@@ -0,0 +1,16 @@
+---
+title: "Leitfaden"
+date: '2026-05-26T00:00:00+08:00'
+weight: 30
+---
+
+Funktionsspezifische Anleitungen zur Nutzung jeder Composia-Fähigkeit:
+
+- [Dienstkonfiguration](service/) — `composia-meta.yaml`, Dienstziele, Netzwerkeinstellungen, Updates, Backups und Migration.
+- [DNS](dns/) — DNS-Provider-Konfiguration und automatische Record-Verwaltung.
+- [Reverse-Proxy](reverse-proxy/) — Caddy-Integration, Synchronisation und Neuladung.
+- [Backups](backups/) — Rustic-basierte Backup-, Restore- und Wartungsvorgänge.
+- [Migration](migrate/) — Dienste zwischen Nodes mit Datenintegrität verschieben.
+- [Secrets](secrets/) — Age-basierte Verschlüsselung für Dienst-Secret-Dateien.
+- [Image-Updates](image-updates/) — Automatische Erkennung und Anwendung von Image-Updates.
+- [Benachrichtigungen](notifications/) — Alertmanager-, SMTP- und Telegram-Benachrichtigungskanäle.
diff --git a/site/content/docs/guide/_index.fr.md b/site/content/docs/guide/_index.fr.md
new file mode 100644
index 0000000..0c44432
--- /dev/null
+++ b/site/content/docs/guide/_index.fr.md
@@ -0,0 +1,16 @@
+---
+title: "Guide"
+date: '2026-05-26T00:00:00+08:00'
+weight: 30
+---
+
+Guides par fonctionnalité couvrant l'utilisation de chaque capacité de Composia :
+
+- [Configuration des services](service/) — `composia-meta.yaml`, cibles de service, paramètres réseau, mises à jour, sauvegardes et migration.
+- [DNS](dns/) — configuration du fournisseur DNS et gestion automatique des enregistrements.
+- [Reverse proxy](reverse-proxy/) — intégration Caddy, synchronisation et rechargement.
+- [Sauvegardes](backups/) — sauvegarde, restauration et maintenance basées sur Rustic.
+- [Migration](migrate/) — déplacer des services entre nœuds avec intégrité des données.
+- [Secrets](secrets/) — chiffrement basé sur age pour les fichiers de secrets de service.
+- [Mises à jour d'images](image-updates/) — détection et application automatiques des mises à jour d'images.
+- [Notifications](notifications/) — canaux de notification Alertmanager, SMTP et Telegram.
diff --git a/site/content/docs/guide/_index.ja.md b/site/content/docs/guide/_index.ja.md
new file mode 100644
index 0000000..326b095
--- /dev/null
+++ b/site/content/docs/guide/_index.ja.md
@@ -0,0 +1,16 @@
+---
+title: "ガイド"
+date: '2026-05-26T00:00:00+08:00'
+weight: 30
+---
+
+各 Composia 機能の使い方を説明する機能別ガイド:
+
+- [サービス設定](service/) - `composia-meta.yaml`、サービスのターゲット、ネットワーク設定、更新、バックアップ、移行。
+- [DNS](dns/) - DNS プロバイダー設定と自動レコード管理。
+- [リバースプロキシ](reverse-proxy/) - Caddy 統合、同期、リロード。
+- [バックアップ](backups/) - Rustic によるバックアップ、リストア、メンテナンス。
+- [移行](migrate/) - データの整合性を保ったままノード間でサービスを移動。
+- [シークレット](secrets/) - サービスのシークレットファイルの Age ベース暗号化。
+- [イメージ更新](image-updates/) - イメージ更新の自動検出と適用。
+- [通知](notifications/) - Alertmanager、SMTP、Telegram 通知チャンネル。
diff --git a/site/content/docs/guide/_index.zh-hans.md b/site/content/docs/guide/_index.zh-hans.md
new file mode 100644
index 0000000..e637129
--- /dev/null
+++ b/site/content/docs/guide/_index.zh-hans.md
@@ -0,0 +1,16 @@
+---
+title: "指南"
+date: '2026-05-26T00:00:00+08:00'
+weight: 30
+---
+
+各功能的专项指南，涵盖如何使用 Composia 的各项能力：
+
+- [服务配置](service/) - `composia-meta.yaml`、服务目标、网络设置、更新、备份和迁移。
+- [DNS](dns/) - DNS 提供商配置与自动记录管理。
+- [反向代理](reverse-proxy/) - Caddy 集成、同步和重载。
+- [备份](backups/) - Rustic 驱动的备份、恢复和维护。
+- [迁移](migrate/) - 在节点之间移动服务并保证数据完整性。
+- [密钥](secrets/) - 基于 age 加密的服务密钥文件。
+- [镜像更新](image-updates/) - 自动镜像更新检测与应用。
+- [通知](notifications/) - Alertmanager、SMTP 和 Telegram 通知渠道。
diff --git a/site/content/docs/guide/_index.zh-hant.md b/site/content/docs/guide/_index.zh-hant.md
new file mode 100644
index 0000000..8117009
--- /dev/null
+++ b/site/content/docs/guide/_index.zh-hant.md
@@ -0,0 +1,16 @@
+---
+title: "指南"
+date: '2026-05-26T00:00:00+08:00'
+weight: 30
+---
+
+針對各功能的指南，涵蓋每個 Composia 功能的使用方式：
+
+- [服務設定](service/) - `composia-meta.yaml`、服務目標、網路設定、更新、備份與遷移。
+- [DNS](dns/) - DNS 提供者設定與自動記錄管理。
+- [反向代理](reverse-proxy/) - Caddy 整合、同步與重新載入。
+- [備份](backups/) - Rustic 驅動的備份、還原與維護。
+- [遷移](migrate/) - 在節點間移動服務並維持資料完整性。
+- [密鑰](secrets/) - 使用 Age 加密服務密鑰檔案。
+- [映像檔更新](image-updates/) - 自動映像檔更新偵測與套用。
+- [通知](notifications/) - Alertmanager、SMTP 與 Telegram 通知管道。
diff --git a/site/content/docs/guide/backups.de.md b/site/content/docs/guide/backups.de.md
new file mode 100644
index 0000000..e7899a5
--- /dev/null
+++ b/site/content/docs/guide/backups.de.md
@@ -0,0 +1,171 @@
+---
+title: "Backups"
+date: '2026-05-26T00:00:00+08:00'
+weight: 40
+---
+
+Composia automatisiert Backups durch Rustic. Backup- und Restore-Aufgaben laufen auf dem Agenten, während der Controller die Laufzeitkonfiguration generiert.
+
+## Architektur
+
+Backups erfordern einen Rustic-Infrastrukturdienst. Das Repository muss genau einen Dienst mit `infra.rustic` deklarieren:
+
+```yaml {filename="rustic/composia-meta.yaml"}
+name: rustic
+nodes:
+ - main
+infra:
+ rustic:
+ compose_service: rustic
+ profile: default
+ data_protect_dir: /data-protect
+```
+
+Der Rustic-Compose-Dienst ist ein normaler Docker-Container, der die `rustic`-Binary ausführt. Er sollte ein Volume für das Data-Protect-Verzeichnis haben.
+
+## Controller-Konfiguration
+
+```yaml
+controller:
+ backup:
+ default_schedule: "0 2 * * *"
+ rustic:
+ main_nodes:
+ - "main"
+ maintenance:
+ forget_schedule: "0 1 * * Sun"
+ prune_schedule: "0 3 * * Sun"
+```
+
+| Schlüssel | Beschreibung |
+|-----|-------------|
+| `backup.default_schedule` | Standard-Cron-Zeitplan für Dienst-Backups. |
+| `rustic.main_nodes` | Node-IDs, auf denen Rustic-Operationen ausgeführt werden. Jede muss auf einen konfigurierten Node verweisen. |
+| `rustic.maintenance.forget_schedule` | Cron-Zeitplan für `rustic forget`. |
+| `rustic.maintenance.prune_schedule` | Cron-Zeitplan für `rustic prune`. |
+
+## Dienst-Datenschutz
+
+Definiere, was gesichert werden soll, in `composia-meta.yaml` unter `data_protect`:
+
+```yaml
+data_protect:
+ data:
+ - name: db
+ backup:
+ strategy: database.pgdumpall
+ service: postgres
+ restore:
+ strategy: database.pgimport
+ service: postgres
+ - name: uploads
+ backup:
+ strategy: files.copy_after_stop
+ include:
+ - ./uploads
+ restore:
+ strategy: files.copy
+ include:
+ - ./uploads
+```
+
+### Datenstrategien
+
+| Strategie | Zweck |
+|----------|---------|
+| `files.copy` | Kopiert Dateien und Verzeichnisse. Für live-lesbare Daten. |
+| `files.copy_after_stop` | Stoppt das Compose-Projekt, kopiert Dateien, startet neu. Für Daten, die ruhiggestellt werden müssen. |
+| `database.pgdumpall` | Führt `pg_dumpall` im Compose-Dienst aus. Erfordert, dass `service` gesetzt ist. |
+| `database.pgimport` | Stellt einen PostgreSQL-Dump über `psql` wieder her. Erfordert, dass `service` gesetzt ist. |
+
+### Datenaktionsfelder
+
+| Schlüssel | Typ | Erforderlich für | Beschreibung |
+|-----|------|-------------|-------------|
+| `strategy` | `string` | Alle | Backup- oder Restore-Strategie. |
+| `service` | `string` | `database.*` | Name des Compose-Dienstes. |
+| `include` | `[]string` | `files.*` | Pfade zum Einbeziehen, relativ zum Dienstverzeichnis. Bleibt innerhalb des Dienststamms. |
+
+### Include-Pfadtypen
+
+Pfade können sich beziehen auf:
+
+- **Dienstpfade**: Dateien oder Verzeichnisse innerhalb des Dienstverzeichnisses. Direkt kopiert.
+- **Benannte Volumes**: Docker-Volume-Namen. Gesichert durch Starten eines temporären Containers, der das Volume einbindet.
+
+## Backup-Zeitpläne
+
+Aktiviere geplante Backups für geschützte Datenelemente:
+
+```yaml
+backup:
+ data:
+ - name: db
+ provider: rustic
+ enabled: true
+ schedule: "0 2 * * *"
+ - name: uploads
+ enabled: true
+ schedule: "0 3 * * Sun"
+```
+
+| Schlüssel | Typ | Erforderlich | Beschreibung |
+|-----|------|----------|-------------|
+| `name` | `string` | Ja | Muss auf einen `data_protect.data[].name` verweisen, der eine Backup-Aktion hat. |
+| `provider` | `string` | Nein | Name des Backup-Providers. |
+| `enabled` | `bool` | Nein | Aktiviert oder deaktiviert dieses Backup. |
+| `schedule` | `string` | Nein | Cron-Ausdruck. `"none"` deaktiviert die Planung, behält aber den Eintrag. |
+
+Wenn `schedule` gesetzt ist, plant der Controller wiederkehrende `backup`-Aufgaben. Der `backup.default_schedule` des Controllers wird als Fallback verwendet, wenn ein Diensteintrag keinen eigenen Zeitplan angibt.
+
+## Wie ein Backup abläuft
+
+Eine Backup-Aufgabe führt diese Schritte auf dem Agenten aus:
+
+1. **Rendern**: Lädt das Dienstpaket und das Rustic-Paket vom Controller herunter. Liest `.composia-backup.json`, das vom Controller generiert wurde.
+2. **Backup**: Für jedes Datenelement in der Laufzeitkonfiguration:
+ - Stellt die Daten gemäß der Backup-Strategie bereit (`files.copy`, `files.copy_after_stop`, `database.pgdumpall`).
+ - Führt `docker compose run rustic backup` mit Tags aus, die den Dienst und das Datenelement identifizieren.
+ - Meldet das Ergebnis (Snapshot-ID) an den Controller.
+3. Die Aufgabe endet, wenn alle Elemente gesichert sind.
+
+Backup-Artefakte werden durch Rustic-Snapshot-IDs identifiziert. Tags enthalten `composia-service:` und `composia-data:` für spätere Restore- und Forget-Operationen.
+
+## Restore
+
+Löse ein Restore über die Web-UI auf der Backups-Seite oder per CLI aus:
+
+```bash
+composia backup restore
+```
+
+Der Restore-Prozess:
+
+1. **Rendern**: Lädt das Dienstpaket und das Rustic-Paket herunter. Liest `.composia-restore.json`.
+2. **Restore**: Für jedes Element:
+ - Führt `docker compose run rustic restore ` aus.
+ - Wendet die wiederhergestellten Daten gemäß der Restore-Strategie an:
+ - `files.copy`: Ersetzt Dateien im Dienstverzeichnis.
+ - `files.copy_after_stop`: Stoppt Compose, ersetzt Dateien, startet Compose neu.
+ - `database.pgimport`: Führt `docker compose exec psql` mit dem wiederhergestellten SQL-Dump aus.
+
+## Rustic-Wartung
+
+Wartungsaufgaben verwenden den Rustic-Infrastrukturdienst:
+
+- **`rustic_init`**: Führt `docker compose run rustic init` aus, um das Rustic-Repository zu initialisieren. Einmal pro Rustic-Setup verwenden.
+- **`rustic_forget`**: Führt `docker compose run rustic forget` mit Tag-Filtern aus. Begrenzt auf einen Dienst, ein Datenelement oder repo-weit.
+- **`rustic_prune`**: Führt `docker compose run rustic prune` aus, um nicht referenzierte Daten zu entfernen.
+
+Löse Wartungsaufgaben über die Web-UI oder CLI aus:
+
+```bash
+composia node init-rustic main
+composia node forget-rustic main
+composia node prune-rustic main
+```
+
+## Siehe auch
+
+- [Dienstkonfiguration](/docs/guide/service/) — Datenschutz und Backup-Planung.
+- [Migration](/docs/guide/migrate/) — Verschiebe Dienste zwischen Nodes mit Datenerhalt durch Backups.
diff --git a/site/content/docs/guide/backups.fr.md b/site/content/docs/guide/backups.fr.md
new file mode 100644
index 0000000..c71ba21
--- /dev/null
+++ b/site/content/docs/guide/backups.fr.md
@@ -0,0 +1,171 @@
+---
+title: "Sauvegardes"
+date: '2026-05-26T00:00:00+08:00'
+weight: 40
+---
+
+Composia automatise les sauvegardes via Rustic. Les tâches de sauvegarde et de restauration s'exécutent sur l'agent, tandis que le contrôleur génère la configuration d'exécution.
+
+## Architecture
+
+Les sauvegardes nécessitent un service d'infrastructure Rustic. Le dépôt doit déclarer exactement un service avec `infra.rustic` :
+
+```yaml {filename="rustic/composia-meta.yaml"}
+name: rustic
+nodes:
+ - main
+infra:
+ rustic:
+ compose_service: rustic
+ profile: default
+ data_protect_dir: /data-protect
+```
+
+Le service Compose Rustic est un conteneur Docker normal exécutant le binaire `rustic`. Il doit avoir un volume pour le répertoire de protection des données.
+
+## Configuration du contrôleur
+
+```yaml
+controller:
+ backup:
+ default_schedule: "0 2 * * *"
+ rustic:
+ main_nodes:
+ - "main"
+ maintenance:
+ forget_schedule: "0 1 * * Sun"
+ prune_schedule: "0 3 * * Sun"
+```
+
+| Clé | Description |
+|-----|-------------|
+| `backup.default_schedule` | Planification cron par défaut pour les sauvegardes de service. |
+| `rustic.main_nodes` | IDs des nœuds où les opérations Rustic s'exécutent. Chaque ID doit référencer un nœud configuré. |
+| `rustic.maintenance.forget_schedule` | Planification cron pour `rustic forget`. |
+| `rustic.maintenance.prune_schedule` | Planification cron pour `rustic prune`. |
+
+## Protection des données de service
+
+Définissez ce qu'il faut sauvegarder dans `composia-meta.yaml` sous `data_protect` :
+
+```yaml
+data_protect:
+ data:
+ - name: db
+ backup:
+ strategy: database.pgdumpall
+ service: postgres
+ restore:
+ strategy: database.pgimport
+ service: postgres
+ - name: uploads
+ backup:
+ strategy: files.copy_after_stop
+ include:
+ - ./uploads
+ restore:
+ strategy: files.copy
+ include:
+ - ./uploads
+```
+
+### Stratégies de données
+
+| Stratégie | Rôle |
+|----------|---------|
+| `files.copy` | Copier des fichiers et répertoires. À utiliser pour les données lisibles en direct. |
+| `files.copy_after_stop` | Arrêter le projet Compose, copier les fichiers, redémarrer. À utiliser pour les données qui doivent être figées. |
+| `database.pgdumpall` | Exécuter `pg_dumpall` à l'intérieur du service Compose. Nécessite que `service` soit défini. |
+| `database.pgimport` | Restaurer un dump PostgreSQL via `psql`. Nécessite que `service` soit défini. |
+
+### Champs d'action de données
+
+| Clé | Type | Requis pour | Description |
+|-----|------|-------------|-------------|
+| `strategy` | `string` | Toutes | Stratégie de sauvegarde ou de restauration. |
+| `service` | `string` | `database.*` | Nom du service Compose. |
+| `include` | `[]string` | `files.*` | Chemins à inclure, relatifs au répertoire du service. Reste à l'intérieur de la racine du service. |
+
+### Types de chemins d'inclusion
+
+Les chemins peuvent référencer :
+
+- **Chemins de service** : fichiers ou répertoires à l'intérieur du répertoire du service. Copiés directement.
+- **Volumes nommés** : noms de volumes Docker. Sauvegardés en lançant un conteneur temporaire qui monte le volume.
+
+## Planifications de sauvegarde
+
+Activez les sauvegardes planifiées pour les éléments de données protégés :
+
+```yaml
+backup:
+ data:
+ - name: db
+ provider: rustic
+ enabled: true
+ schedule: "0 2 * * *"
+ - name: uploads
+ enabled: true
+ schedule: "0 3 * * Sun"
+```
+
+| Clé | Type | Requis | Description |
+|-----|------|----------|-------------|
+| `name` | `string` | Oui | Doit référencer un `data_protect.data[].name` qui a une action de sauvegarde. |
+| `provider` | `string` | Non | Nom du fournisseur de sauvegarde. |
+| `enabled` | `bool` | Non | Activer ou désactiver cette sauvegarde. |
+| `schedule` | `string` | Non | Expression cron. `"none"` désactive la planification tout en conservant l'entrée. |
+
+Lorsque `schedule` est défini, le contrôleur planifie des tâches `backup` récurrentes. La valeur `backup.default_schedule` du contrôleur est utilisée comme valeur de repli si une entrée de service ne spécifie pas sa propre planification.
+
+## Déroulement d'une sauvegarde
+
+Une tâche de sauvegarde exécute ces étapes sur l'agent :
+
+1. **Rendu** : télécharger le bundle de service et le bundle Rustic depuis le contrôleur. Lire `.composia-backup.json` généré par le contrôleur.
+2. **Sauvegarde** : pour chaque élément de données dans la configuration d'exécution :
+ - Préparer les données selon la stratégie de sauvegarde (`files.copy`, `files.copy_after_stop`, `database.pgdumpall`).
+ - Exécuter `docker compose run rustic backup` avec des balises identifiant le service et l'élément de données.
+ - Rapporter le résultat (ID du snapshot) au contrôleur.
+3. La tâche se termine lorsque tous les éléments sont sauvegardés.
+
+Les artefacts de sauvegarde sont identifiés par les IDs de snapshot Rustic. Les balises incluent `composia-service:` et `composia-data:` pour les opérations ultérieures de restauration et d'oubli.
+
+## Restauration
+
+Déclenchez une restauration via l'interface web depuis la page des sauvegardes ou via la CLI :
+
+```bash
+composia backup restore
+```
+
+Le processus de restauration :
+
+1. **Rendu** : télécharger le bundle de service et le bundle Rustic. Lire `.composia-restore.json`.
+2. **Restauration** : pour chaque élément :
+ - Exécuter `docker compose run rustic restore `.
+ - Appliquer les données restaurées selon la stratégie de restauration :
+ - `files.copy` : remplacer les fichiers dans le répertoire du service.
+ - `files.copy_after_stop` : arrêter Compose, remplacer les fichiers, redémarrer Compose.
+ - `database.pgimport` : exécuter `docker compose exec psql` avec le dump SQL restauré.
+
+## Maintenance Rustic
+
+Les tâches de maintenance utilisent le service d'infrastructure Rustic :
+
+- **`rustic_init`** : exécute `docker compose run rustic init` pour initialiser le dépôt Rustic. À utiliser une fois par configuration Rustic.
+- **`rustic_forget`** : exécute `docker compose run rustic forget` avec des filtres de balises. Limité à un service, un élément de données ou l'ensemble du dépôt.
+- **`rustic_prune`** : exécute `docker compose run rustic prune` pour supprimer les données non référencées.
+
+Déclenchez la maintenance depuis l'interface web ou la CLI :
+
+```bash
+composia node init-rustic main
+composia node forget-rustic main
+composia node prune-rustic main
+```
+
+## Voir aussi
+
+- [Configuration des services](/docs/guide/service/) — protection des données et planification des sauvegardes.
+- [Migration](/docs/guide/migrate/) — déplacer des services entre nœuds avec les données préservées via les sauvegardes.
diff --git a/site/content/docs/guide/backups.ja.md b/site/content/docs/guide/backups.ja.md
new file mode 100644
index 0000000..9f874ea
--- /dev/null
+++ b/site/content/docs/guide/backups.ja.md
@@ -0,0 +1,171 @@
+---
+title: "バックアップ"
+date: '2026-05-26T00:00:00+08:00'
+weight: 40
+---
+
+Composia は Rustic を通じてバックアップを自動化します。バックアップとリストアのタスクはエージェント上で実行され、コントローラーがランタイム設定を生成します。
+
+## アーキテクチャ
+
+バックアップには Rustic インフラストラクチャサービスが必要です。リポジトリには `infra.rustic` を持つサービスを 1 つだけ宣言する必要があります:
+
+```yaml {filename="rustic/composia-meta.yaml"}
+name: rustic
+nodes:
+ - main
+infra:
+ rustic:
+ compose_service: rustic
+ profile: default
+ data_protect_dir: /data-protect
+```
+
+Rustic compose サービスは `rustic` バイナリを実行する通常の Docker コンテナです。データ保護ディレクトリ用のボリュームが必要です。
+
+## コントローラー設定
+
+```yaml
+controller:
+ backup:
+ default_schedule: "0 2 * * *"
+ rustic:
+ main_nodes:
+ - "main"
+ maintenance:
+ forget_schedule: "0 1 * * Sun"
+ prune_schedule: "0 3 * * Sun"
+```
+
+| キー | 説明 |
+|-----|-------------|
+| `backup.default_schedule` | サービスバックアップのデフォルト cron スケジュール。 |
+| `rustic.main_nodes` | Rustic 操作を実行するノード ID。それぞれ設定されたノードを参照する必要があります。 |
+| `rustic.maintenance.forget_schedule` | `rustic forget` の cron スケジュール。 |
+| `rustic.maintenance.prune_schedule` | `rustic prune` の cron スケジュール。 |
+
+## サービスデータ保護
+
+`composia-meta.yaml` の `data_protect` でバックアップ対象を定義します:
+
+```yaml
+data_protect:
+ data:
+ - name: db
+ backup:
+ strategy: database.pgdumpall
+ service: postgres
+ restore:
+ strategy: database.pgimport
+ service: postgres
+ - name: uploads
+ backup:
+ strategy: files.copy_after_stop
+ include:
+ - ./uploads
+ restore:
+ strategy: files.copy
+ include:
+ - ./uploads
+```
+
+### データ戦略
+
+| 戦略 | 目的 |
+|----------|---------|
+| `files.copy` | ファイルとディレクトリをコピー。読み取り中のデータに使用します。 |
+| `files.copy_after_stop` | compose プロジェクトを停止し、ファイルをコピーしてから再起動。静止状態が必要なデータに使用します。 |
+| `database.pgdumpall` | compose サービス内で `pg_dumpall` を実行。`service` の設定が必須です。 |
+| `database.pgimport` | `psql` で PostgreSQL ダンプをリストア。`service` の設定が必須です。 |
+
+### データアクションフィールド
+
+| キー | 型 | 必須 | 説明 |
+|-----|------|-------------|-------------|
+| `strategy` | `string` | すべて | バックアップまたはリストアの戦略。 |
+| `service` | `string` | `database.*` | Compose サービス名。 |
+| `include` | `[]string` | `files.*` | 含めるパス。サービスディレクトリからの相対パス。サービスルート内に留まります。 |
+
+### include パスの種類
+
+パスは以下を参照できます:
+
+- **サービスパス**: サービスディレクトリ内のファイルまたはディレクトリ。直接コピーされます。
+- **名前付きボリューム**: Docker ボリューム名。ボリュームをマウントする一時コンテナを起動してバックアップします。
+
+## バックアップスケジュール
+
+保護されたデータ項目のスケジュールバックアップを有効にします:
+
+```yaml
+backup:
+ data:
+ - name: db
+ provider: rustic
+ enabled: true
+ schedule: "0 2 * * *"
+ - name: uploads
+ enabled: true
+ schedule: "0 3 * * Sun"
+```
+
+| キー | 型 | 必須 | 説明 |
+|-----|------|----------|-------------|
+| `name` | `string` | はい | バックアップアクションを持つ `data_protect.data[].name` を参照する必要があります。 |
+| `provider` | `string` | いいえ | バックアッププロバイダー名。 |
+| `enabled` | `bool` | いいえ | このバックアップを有効または無効にします。 |
+| `schedule` | `string` | いいえ | cron 式。`"none"` はエントリを保持したままスケジュールを無効にします。 |
+
+`schedule` が設定されている場合、コントローラーは定期的な `backup` タスクをスケジュールします。サービスエントリが独自のスケジュールを指定していない場合、コントローラーの `backup.default_schedule` がフォールバックとして使用されます。
+
+## バックアップの実行方法
+
+バックアップタスクはエージェント上で以下のステップを実行します:
+
+1. **レンダリング**: コントローラーからサービスバンドルと Rustic バンドルをダウンロード。コントローラーが生成した `.composia-backup.json` を読み取ります。
+2. **バックアップ**: ランタイム設定の各データ項目について:
+ - バックアップ戦略（`files.copy`、`files.copy_after_stop`、`database.pgdumpall`）に従ってデータをステージングします。
+ - サービスとデータ項目を識別するタグを付けて `docker compose run rustic backup` を実行します。
+ - 結果（スナップショット ID）をコントローラーに報告します。
+3. すべての項目がバックアップされたらタスクが完了します。
+
+バックアップ成果物は Rustic スナップショット ID で識別されます。タグには後続のリストアや forget 操作用に `composia-service:` と `composia-data:` が含まれます。
+
+## リストア
+
+Web UI のバックアップページから、または CLI でリストアをトリガーします:
+
+```bash
+composia backup restore
+```
+
+リストアプロセス:
+
+1. **レンダリング**: サービスバンドルと Rustic バンドルをダウンロード。`.composia-restore.json` を読み取ります。
+2. **リストア**: 各項目について:
+ - `docker compose run rustic restore ` を実行します。
+ - リストア戦略に従って復元されたデータを適用します:
+ - `files.copy`: サービスディレクトリのファイルを置き換えます。
+ - `files.copy_after_stop`: compose を停止し、ファイルを置き換え、compose を再起動します。
+ - `database.pgimport`: 復元された SQL ダンプで `docker compose exec psql` を実行します。
+
+## Rustic メンテナンス
+
+メンテナンスタスクは Rustic インフラストラクチャサービスを使用します:
+
+- **`rustic_init`**: `docker compose run rustic init` を実行して Rustic リポジトリを初期化します。Rustic セットアップごとに 1 回使用します。
+- **`rustic_forget`**: タグフィルター付きで `docker compose run rustic forget` を実行します。サービス、データ項目、またはリポジトリ全体にスコープを設定できます。
+- **`rustic_prune`**: `docker compose run rustic prune` を実行して参照されていないデータを削除します。
+
+Web UI または CLI からメンテナンスをトリガーします:
+
+```bash
+composia node init-rustic main
+composia node forget-rustic main
+composia node prune-rustic main
+```
+
+## 関連項目
+
+- [サービス設定](/docs/guide/service/) — データ保護とバックアップスケジュール。
+- [移行](/docs/guide/migrate/) — バックアップを通じてデータを保持したままノード間でサービスを移動。
diff --git a/site/content/docs/guide/backups.zh-hans.md b/site/content/docs/guide/backups.zh-hans.md
new file mode 100644
index 0000000..314a34b
--- /dev/null
+++ b/site/content/docs/guide/backups.zh-hans.md
@@ -0,0 +1,171 @@
+---
+title: "备份"
+date: '2026-05-26T00:00:00+08:00'
+weight: 40
+---
+
+Composia 通过 Rustic 实现自动备份。备份和恢复任务在 agent 上运行，而控制器负责生成运行时配置。
+
+## 架构
+
+备份需要一个 Rustic 基础设施服务。仓库中必须声明一个带有 `infra.rustic` 的服务：
+
+```yaml {filename="rustic/composia-meta.yaml"}
+name: rustic
+nodes:
+ - main
+infra:
+ rustic:
+ compose_service: rustic
+ profile: default
+ data_protect_dir: /data-protect
+```
+
+Rustic compose 服务是一个运行 `rustic` 二进制文件的普通 Docker 容器。它应该有一个用于数据保护目录的卷。
+
+## 控制器配置
+
+```yaml
+controller:
+ backup:
+ default_schedule: "0 2 * * *"
+ rustic:
+ main_nodes:
+ - "main"
+ maintenance:
+ forget_schedule: "0 1 * * Sun"
+ prune_schedule: "0 3 * * Sun"
+```
+
+| 键 | 描述 |
+|-----|-------------|
+| `backup.default_schedule` | 服务备份的默认 cron 计划。 |
+| `rustic.main_nodes` | 运行 Rustic 操作的节点 ID 列表。每个都必须引用已配置的节点。 |
+| `rustic.maintenance.forget_schedule` | `rustic forget` 的 cron 计划。 |
+| `rustic.maintenance.prune_schedule` | `rustic prune` 的 cron 计划。 |
+
+## 服务数据保护
+
+在 `composia-meta.yaml` 的 `data_protect` 下定义要备份的内容：
+
+```yaml
+data_protect:
+ data:
+ - name: db
+ backup:
+ strategy: database.pgdumpall
+ service: postgres
+ restore:
+ strategy: database.pgimport
+ service: postgres
+ - name: uploads
+ backup:
+ strategy: files.copy_after_stop
+ include:
+ - ./uploads
+ restore:
+ strategy: files.copy
+ include:
+ - ./uploads
+```
+
+### 数据策略
+
+| 策略 | 用途 |
+|----------|---------|
+| `files.copy` | 复制文件和目录。用于可实时读取的数据。 |
+| `files.copy_after_stop` | 停止 compose 项目，复制文件，然后重新启动。用于需要静止状态的数据。 |
+| `database.pgdumpall` | 在 compose 服务内运行 `pg_dumpall`。需要设置 `service`。 |
+| `database.pgimport` | 通过 `psql` 恢复 PostgreSQL 转储。需要设置 `service`。 |
+
+### 数据操作字段
+
+| 键 | 类型 | 适用于 | 描述 |
+|-----|------|-------------|-------------|
+| `strategy` | `string` | 全部 | 备份或恢复策略。 |
+| `service` | `string` | `database.*` | Compose 服务名称。 |
+| `include` | `[]string` | `files.*` | 要包含的路径，相对于服务目录。不能超出服务根目录。 |
+
+### 包含路径类型
+
+路径可以引用：
+
+- **服务路径**: 服务目录内的文件或目录，直接复制。
+- **命名卷**: Docker 卷名。通过启动一个挂载该卷的临时容器进行备份。
+
+## 备份计划
+
+为受保护的数据项启用定时备份：
+
+```yaml
+backup:
+ data:
+ - name: db
+ provider: rustic
+ enabled: true
+ schedule: "0 2 * * *"
+ - name: uploads
+ enabled: true
+ schedule: "0 3 * * Sun"
+```
+
+| 键 | 类型 | 必填 | 描述 |
+|-----|------|----------|-------------|
+| `name` | `string` | 是 | 必须引用具有备份操作的 `data_protect.data[].name`。 |
+| `provider` | `string` | 否 | 备份提供者名称。 |
+| `enabled` | `bool` | 否 | 启用或禁用此备份。 |
+| `schedule` | `string` | 否 | Cron 表达式。`"none"` 表示禁用调度但保留该条目。 |
+
+当设置了 `schedule` 时，控制器会调度重复的 `backup` 任务。如果服务条目未指定自己的计划，则使用控制器的 `backup.default_schedule` 作为回退。
+
+## 备份执行流程
+
+备份任务在 agent 上执行以下步骤：
+
+1. **渲染**: 从控制器下载服务包和 Rustic 包。读取由控制器生成的 `.composia-backup.json`。
+2. **备份**: 对运行时配置中的每个数据项：
+ - 根据备份策略（`files.copy`、`files.copy_after_stop`、`database.pgdumpall`）准备数据。
+ - 运行 `docker compose run rustic backup`，并带上标识服务和数据项的标签。
+ - 将结果（快照 ID）上报给控制器。
+3. 所有项备份完成，任务结束。
+
+备份产物由 Rustic 快照 ID 标识。标签包含 `composia-service:` 和 `composia-data:`，用于后续的恢复和清理操作。
+
+## 恢复
+
+通过 Web UI 的备份页面或 CLI 触发恢复：
+
+```bash
+composia backup restore
+```
+
+恢复过程：
+
+1. **渲染**: 下载服务包和 Rustic 包。读取 `.composia-restore.json`。
+2. **恢复**: 对每个项：
+ - 运行 `docker compose run rustic restore `。
+ - 根据恢复策略应用恢复的数据：
+ - `files.copy`: 替换服务目录中的文件。
+ - `files.copy_after_stop`: 停止 compose，替换文件，重启 compose。
+ - `database.pgimport`: 使用恢复的 SQL 转储运行 `docker compose exec psql`。
+
+## Rustic 维护
+
+维护任务使用 Rustic 基础设施服务：
+
+- **`rustic_init`**: 运行 `docker compose run rustic init` 初始化 Rustic 仓库。每个 Rustic 设置只需使用一次。
+- **`rustic_forget`**: 运行 `docker compose run rustic forget` 并带标签过滤器。作用域可以是某个服务、数据项或整个仓库。
+- **`rustic_prune`**: 运行 `docker compose run rustic prune` 删除未引用的数据。
+
+通过 Web UI 或 CLI 触发维护：
+
+```bash
+composia node init-rustic main
+composia node forget-rustic main
+composia node prune-rustic main
+```
+
+## 另请参阅
+
+- [服务配置](/docs/guide/service/) — 数据保护和备份调度。
+- [迁移](/docs/guide/migrate/) — 在节点之间移动服务并通过备份保留数据。
diff --git a/site/content/docs/guide/backups.zh-hant.md b/site/content/docs/guide/backups.zh-hant.md
new file mode 100644
index 0000000..04e6e68
--- /dev/null
+++ b/site/content/docs/guide/backups.zh-hant.md
@@ -0,0 +1,171 @@
+---
+title: "備份"
+date: '2026-05-26T00:00:00+08:00'
+weight: 40
+---
+
+Composia 透過 Rustic 自動化備份。備份與還原任務在代理端執行，控制器則產生執行時期設定。
+
+## 架構
+
+備份需要一個 Rustic 基礎架構服務。存放庫中必須恰好宣告一個帶有 `infra.rustic` 的服務：
+
+```yaml {filename="rustic/composia-meta.yaml"}
+name: rustic
+nodes:
+ - main
+infra:
+ rustic:
+ compose_service: rustic
+ profile: default
+ data_protect_dir: /data-protect
+```
+
+Rustic compose 服務是一個執行 `rustic` 二進位檔的普通 Docker 容器，應有一個掛載資料保護目錄的磁碟區。
+
+## 控制器設定
+
+```yaml
+controller:
+ backup:
+ default_schedule: "0 2 * * *"
+ rustic:
+ main_nodes:
+ - "main"
+ maintenance:
+ forget_schedule: "0 1 * * Sun"
+ prune_schedule: "0 3 * * Sun"
+```
+
+| 鍵 | 說明 |
+|-----|-------------|
+| `backup.default_schedule` | 服務備份的預設 cron 排程。 |
+| `rustic.main_nodes` | 執行 Rustic 操作的節點 ID。每個都必須引用已設定的節點。 |
+| `rustic.maintenance.forget_schedule` | `rustic forget` 的 cron 排程。 |
+| `rustic.maintenance.prune_schedule` | `rustic prune` 的 cron 排程。 |
+
+## 服務資料保護
+
+在 `composia-meta.yaml` 中的 `data_protect` 下定義要備份的內容：
+
+```yaml
+data_protect:
+ data:
+ - name: db
+ backup:
+ strategy: database.pgdumpall
+ service: postgres
+ restore:
+ strategy: database.pgimport
+ service: postgres
+ - name: uploads
+ backup:
+ strategy: files.copy_after_stop
+ include:
+ - ./uploads
+ restore:
+ strategy: files.copy
+ include:
+ - ./uploads
+```
+
+### 資料策略
+
+| 策略 | 用途 |
+|----------|---------|
+| `files.copy` | 複製檔案與目錄。用於可即時讀取的資料。 |
+| `files.copy_after_stop` | 停止 compose 專案、複製檔案、重新啟動。用於需要靜止狀態的資料。 |
+| `database.pgdumpall` | 在 compose 服務內執行 `pg_dumpall`。需要設定 `service`。 |
+| `database.pgimport` | 透過 `psql` 還原 PostgreSQL 傾印。需要設定 `service`。 |
+
+### 資料操作欄位
+
+| 鍵 | 型別 | 對以下項目為必要 | 說明 |
+|-----|------|-------------|-------------|
+| `strategy` | `string` | 全部 | 備份或還原策略。 |
+| `service` | `string` | `database.*` | Compose 服務名稱。 |
+| `include` | `[]string` | `files.*` | 要包含的路徑，相對於服務目錄。保持在服務根目錄內。 |
+
+### 包含路徑型別
+
+路徑可以引用：
+
+- **服務路徑**：服務目錄內的檔案或目錄。直接複製。
+- **具名磁碟區**：Docker 磁碟區名稱。透過啟動掛載該磁碟區的臨時容器進行備份。
+
+## 備份排程
+
+為受保護的資料項目啟用排程備份：
+
+```yaml
+backup:
+ data:
+ - name: db
+ provider: rustic
+ enabled: true
+ schedule: "0 2 * * *"
+ - name: uploads
+ enabled: true
+ schedule: "0 3 * * Sun"
+```
+
+| 鍵 | 型別 | 必要 | 說明 |
+|-----|------|----------|-------------|
+| `name` | `string` | 是 | 必須引用具有備份操作的 `data_protect.data[].name`。 |
+| `provider` | `string` | 否 | 備份提供者名稱。 |
+| `enabled` | `bool` | 否 | 啟用或停用此備份。 |
+| `schedule` | `string` | 否 | Cron 表達式。`"none"` 停用排程但保留項目。 |
+
+當設定 `schedule` 時，控制器會排程週期性的 `backup` 任務。若服務項目未指定自己的排程，則使用控制器的 `backup.default_schedule` 作為後備。
+
+## 備份執行方式
+
+備份任務在代理端執行以下步驟：
+
+1. **渲染**：從控制器下載服務包與 Rustic 包。讀取控制器產生的 `.composia-backup.json`。
+2. **備份**：針對執行時期設定中的每個資料項目：
+ - 根據備份策略（`files.copy`、`files.copy_after_stop`、`database.pgdumpall`）暫存資料。
+ - 執行 `docker compose run rustic backup`，並加上識別服務與資料項目的標籤。
+ - 將結果（快照 ID）回報給控制器。
+3. 所有項目備份完成後，任務結束。
+
+備份成品以 Rustic 快照 ID 識別。標籤包含 `composia-service:` 和 `composia-data:`，用於後續的還原與 forget 操作。
+
+## 還原
+
+透過 Web UI 從備份頁面觸發還原，或使用 CLI：
+
+```bash
+composia backup restore
+```
+
+還原流程：
+
+1. **渲染**：下載服務包與 Rustic 包。讀取 `.composia-restore.json`。
+2. **還原**：針對每個項目：
+ - 執行 `docker compose run rustic restore `。
+ - 根據還原策略套用已還原的資料：
+ - `files.copy`：取代服務目錄中的檔案。
+ - `files.copy_after_stop`：停止 compose、取代檔案、重新啟動 compose。
+ - `database.pgimport`：使用還原的 SQL 傾印執行 `docker compose exec psql`。
+
+## Rustic 維護
+
+維護任務使用 Rustic 基礎架構服務：
+
+- **`rustic_init`**：執行 `docker compose run rustic init` 以初始化 Rustic 存放庫。每個 Rustic 設定使用一次。
+- **`rustic_forget`**：執行 `docker compose run rustic forget` 並套用標籤過濾。可限定範圍為服務、資料項目或整個存放庫。
+- **`rustic_prune`**：執行 `docker compose run rustic prune` 以移除未引用的資料。
+
+從 Web UI 或 CLI 觸發維護：
+
+```bash
+composia node init-rustic main
+composia node forget-rustic main
+composia node prune-rustic main
+```
+
+## 參見
+
+- [服務設定](/docs/guide/service/) — 資料保護與備份排程。
+- [遷移](/docs/guide/migrate/) — 在節點間移動服務，透過備份保留資料。
diff --git a/site/content/docs/guide/dns.de.md b/site/content/docs/guide/dns.de.md
new file mode 100644
index 0000000..8d8b9a5
--- /dev/null
+++ b/site/content/docs/guide/dns.de.md
@@ -0,0 +1,125 @@
+---
+title: "DNS"
+date: '2026-05-26T00:00:00+08:00'
+weight: 20
+---
+
+Composia verwaltet DNS-Records für Dienste, die `network.dns` deklarieren. DNS-Updates laufen als controller-seitige Aufgaben.
+
+## Wie es funktioniert
+
+Wenn ein Dienst deployed wird oder ein DNS-Update manuell ausgelöst wird, erstellt der Controller eine `dns_update`-Aufgabe. Der Controller-Worker führt sie aus:
+
+1. Liest die Dienst-Meta beim in der Aufgabe aufgezeichneten Repo-Revision.
+2. Erstellt die gewünschten DNS-Records aus `network.dns`.
+3. Synchronisiert die Records mit dem DNS-Provider.
+
+## Provider-Konfiguration
+
+Konfiguriere mindestens einen DNS-Provider in der Controller-Konfiguration. Die Provider-Anmeldeinformationen und Zonenliste sind global:
+
+```yaml
+controller:
+ dns:
+ cloudflare:
+ api_token: "REPLACE"
+ zones:
+ - "example.com"
+ - "other.com"
+```
+
+Fünf Provider werden unterstützt. Jeder hat seine eigenen Anmeldeschlüssel und alle teilen ein `zones`-Feld, das die verwalteten Domain-Zonen auflistet:
+
+| Provider | Schlüsselpräfix | Anmeldeschlüssel |
+|----------|-----------|-----------------|
+| `cloudflare` | `dns.cloudflare` | `api_token`, `api_token_file` |
+| `alidns` | `dns.alidns` | `access_key_id`, `access_key_secret`, `region_id`, optional `security_token` |
+| `dnspod` | `dns.dnspod` | `secret_id`, `secret_key`, `region`, optional `session_token` |
+| `route53` | `dns.route53` | `access_key_id`, `secret_access_key`, `region`, optional `session_token`, `profile`, `hosted_zone_id` |
+| `huaweicloud` | `dns.huaweicloud` | `access_key_id`, `secret_access_key`, `region_id` |
+
+Jedes Anmeldefeld hat eine entsprechende `_file`-Variante zum Lesen aus einer Datei (zum Beispiel `api_token_file`).
+
+## Dienst-DNS-Deklaration
+
+Deklariere DNS-Einstellungen in der `composia-meta.yaml` des Dienstes:
+
+```yaml
+network:
+ dns:
+ provider: cloudflare
+ hostname: app.example.com
+ record_type: A
+ value: 203.0.113.10
+ proxied: true
+ ttl: 120
+ comment: "Verwaltet von Composia"
+```
+
+| Schlüssel | Typ | Erforderlich | Beschreibung |
+|-----|------|----------|-------------|
+| `provider` | `string` | Ja | `cloudflare`, `alidns`, `dnspod`, `route53` oder `huaweicloud`. |
+| `hostname` | `string` | Ja | DNS-Hostname. Die Zone wird aus der konfigurierten Zonenliste abgeglichen. |
+| `record_type` | `string` | Nein | `A`, `AAAA` oder `CNAME`. Wenn leer, wird der Record-Typ aus dem Wert oder den Node-Adressen abgeleitet. |
+| `value` | `string` | Nein | Expliziter DNS-Record-Wert. Wenn leer, leitet Composia den Wert vom Ziel-Node ab. |
+| `proxied` | `bool` | Nein | Aktiviert den Cloudflare-Proxy. Wird nur von Cloudflare unterstützt. |
+| `ttl` | `uint32` | Nein | DNS-TTL in Sekunden. |
+| `comment` | `string` | Nein | DNS-Record-Kommentar. Wird nur von Cloudflare unterstützt. |
+
+## Record-Auflösung
+
+### Mit einem expliziten Wert
+
+Wenn `value` gesetzt ist, verwendet Composia ihn direkt. Wenn es eine IP-Adresse ist, wird der Record-Typ abgeleitet: IPv4 wird zu `A`, IPv6 wird zu `AAAA`. Wenn es ein Hostname ist, muss der Record-Typ `CNAME` sein (oder leer, was ebenfalls zu `CNAME` aufgelöst wird).
+
+```yaml
+network:
+ dns:
+ provider: cloudflare
+ hostname: app.example.com
+ value: 203.0.113.10
+```
+
+### Von Node-Adressen
+
+Wenn `value` leer ist, verwendet Composia die `public_ipv4` und `public_ipv6` des Ziel-Nodes aus der Controller-Konfiguration:
+
+```yaml
+controller:
+ nodes:
+ - id: "main"
+ public_ipv4: "203.0.113.10"
+ public_ipv6: "2001:db8::10"
+```
+
+Bei leerem `record_type` werden sowohl A- als auch AAAA-Records erstellt, wenn der Node beide Adressen hat. Wenn `record_type` `A` ist, wird nur die IPv4-Adresse verwendet. Wenn `record_type` `AAAA` ist, wird nur die IPv6-Adresse verwendet.
+
+Dienste, die mehr als einen Node anvisieren, müssen `value` explizit setzen. Ein leeres `value` mit mehreren Ziel-Nodes erzeugt einen Fehler.
+
+## DNS-Updates auslösen
+
+DNS-Records werden während des Deploy-Aufgabenablaufs erstellt oder aktualisiert. Du kannst auch ein eigenständiges DNS-Update über die Web-UI oder CLI auslösen:
+
+```bash
+composia service dns-update my-app
+```
+
+Dies erstellt eine `dns_update`-Aufgabe. Das Aufgabenprotokoll zeigt die Zonenauflösung, Record-Operationen und das Endergebnis.
+
+## Cloudflare-Optionen
+
+Wenn der Provider `cloudflare` ist, werden `proxied` und `comment` nach der Record-Erstellung angewendet. Composia ruft die Cloudflare-API auf, um jeden DNS-Record mit dem angeforderten Proxy-Status und Kommentar zu patchen.
+
+Nicht-Cloudflare-Provider unterstützen diese Optionen nicht. Das Setzen von `proxied` oder `comment` mit einem anderen Provider führt zum Fehlschlag des DNS-Updates.
+
+## Zonenabgleich
+
+Composia gleicht den Dienst-Hostnamen mit den konfigurierten Zonen ab. Zonen werden von der längsten zur kürzesten Übereinstimmung durchprobiert. Zum Beispiel, mit `zones: ["example.com.", "sub.example.com."]`, passt der Hostname `app.sub.example.com` zuerst zu `sub.example.com.`.
+
+Wenn keine Zone zum Hostnamen passt, schlägt das DNS-Update fehl.
+
+## Bereinigung veralteter Records
+
+Die DNS-Synchronisation verwaltet genau drei Record-Typen pro Hostname: A, AAAA und CNAME. Jeder konfigurierte Record-Typ, der nicht im Sollzustand vorhanden ist, wird gelöscht, bevor neue Records gesetzt werden. Wenn zum Beispiel ein Dienst zuvor `record_type: A` hatte und zu `record_type: CNAME` wechselt, wird der alte A-Record entfernt und ein neuer CNAME-Record erstellt.
+
+Das Ändern des Hostnamens eines Dienstes bereinigt keine Records für den alten Hostnamen. Wenn du `app.example.com` in `api.example.com` umbenennst, bleiben die Records für `app.example.com` im DNS-Provider, bis du sie manuell entfernst.
diff --git a/site/content/docs/guide/dns.fr.md b/site/content/docs/guide/dns.fr.md
new file mode 100644
index 0000000..7e79dd6
--- /dev/null
+++ b/site/content/docs/guide/dns.fr.md
@@ -0,0 +1,125 @@
+---
+title: "DNS"
+date: '2026-05-26T00:00:00+08:00'
+weight: 20
+---
+
+Composia gère les enregistrements DNS pour les services qui déclarent `network.dns`. Les mises à jour DNS s'exécutent comme des tâches côté contrôleur.
+
+## Fonctionnement
+
+Lorsqu'un service est déployé ou qu'une mise à jour DNS est déclenchée manuellement, le contrôleur crée une tâche `dns_update`. Le worker du contrôleur l'exécute :
+
+1. Lire les métadonnées du service à la révision du dépôt enregistrée dans la tâche.
+2. Construire les enregistrements DNS souhaités à partir de `network.dns`.
+3. Synchroniser les enregistrements avec le fournisseur DNS.
+
+## Configuration du fournisseur
+
+Configurez au moins un fournisseur DNS dans la configuration du contrôleur. Les identifiants du fournisseur et la liste des zones sont globaux :
+
+```yaml
+controller:
+ dns:
+ cloudflare:
+ api_token: "REPLACE"
+ zones:
+ - "example.com"
+ - "other.com"
+```
+
+Cinq fournisseurs sont pris en charge. Chacun a ses propres clés d'identifiants et partage un champ `zones` listant les zones de domaine gérées :
+
+| Fournisseur | Préfixe de clé | Clés d'identifiants |
+|----------|-----------|-----------------|
+| `cloudflare` | `dns.cloudflare` | `api_token`, `api_token_file` |
+| `alidns` | `dns.alidns` | `access_key_id`, `access_key_secret`, `region_id`, optionnel `security_token` |
+| `dnspod` | `dns.dnspod` | `secret_id`, `secret_key`, `region`, optionnel `session_token` |
+| `route53` | `dns.route53` | `access_key_id`, `secret_access_key`, `region`, optionnel `session_token`, `profile`, `hosted_zone_id` |
+| `huaweicloud` | `dns.huaweicloud` | `access_key_id`, `secret_access_key`, `region_id` |
+
+Chaque champ d'identifiant a une variante `_file` correspondante pour la lecture depuis un fichier (par exemple `api_token_file`).
+
+## Déclaration DNS du service
+
+Déclarez les paramètres DNS dans le fichier `composia-meta.yaml` du service :
+
+```yaml
+network:
+ dns:
+ provider: cloudflare
+ hostname: app.example.com
+ record_type: A
+ value: 203.0.113.10
+ proxied: true
+ ttl: 120
+ comment: "Managed by Composia"
+```
+
+| Clé | Type | Requis | Description |
+|-----|------|----------|-------------|
+| `provider` | `string` | Oui | `cloudflare`, `alidns`, `dnspod`, `route53` ou `huaweicloud`. |
+| `hostname` | `string` | Oui | Nom d'hôte DNS. La zone est mise en correspondance avec la liste des zones configurées. |
+| `record_type` | `string` | Non | `A`, `AAAA` ou `CNAME`. Si vide, le type d'enregistrement est déduit de la valeur ou des adresses du nœud. |
+| `value` | `string` | Non | Valeur explicite de l'enregistrement DNS. Si vide, Composia déduit la valeur du nœud cible. |
+| `proxied` | `bool` | Non | Activer le proxy Cloudflare. Uniquement pris en charge par Cloudflare. |
+| `ttl` | `uint32` | Non | TTL DNS en secondes. |
+| `comment` | `string` | Non | Commentaire de l'enregistrement DNS. Uniquement pris en charge par Cloudflare. |
+
+## Résolution des enregistrements
+
+### Avec une valeur explicite
+
+Lorsque `value` est défini, Composia l'utilise directement. S'il s'agit d'une adresse IP, le type d'enregistrement est déduit : IPv4 devient `A`, IPv6 devient `AAAA`. S'il s'agit d'un nom d'hôte, le type d'enregistrement doit être `CNAME` (ou vide, ce qui résout également en `CNAME`).
+
+```yaml
+network:
+ dns:
+ provider: cloudflare
+ hostname: app.example.com
+ value: 203.0.113.10
+```
+
+### À partir des adresses du nœud
+
+Lorsque `value` est vide, Composia utilise les adresses `public_ipv4` et `public_ipv6` du nœud cible depuis la configuration du contrôleur :
+
+```yaml
+controller:
+ nodes:
+ - id: "main"
+ public_ipv4: "203.0.113.10"
+ public_ipv6: "2001:db8::10"
+```
+
+Avec un `record_type` vide, les enregistrements A et AAAA sont créés lorsque le nœud a les deux adresses. Si `record_type` est `A`, seule l'adresse IPv4 est utilisée. Si `record_type` est `AAAA`, seule l'adresse IPv6 est utilisée.
+
+Les services qui ciblent plus d'un nœud doivent définir `value` explicitement. Un `value` vide avec plusieurs nœuds cibles produit une erreur.
+
+## Déclencher les mises à jour DNS
+
+Les enregistrements DNS sont créés ou mis à jour pendant le flux de tâche de déploiement. Vous pouvez également déclencher une mise à jour DNS autonome via l'interface web ou la CLI :
+
+```bash
+composia service dns-update my-app
+```
+
+Cela crée une tâche `dns_update`. Le journal de la tâche montre la résolution de zone, les opérations d'enregistrement et le résultat final.
+
+## Options Cloudflare
+
+Lorsque le fournisseur est `cloudflare`, `proxied` et `comment` sont appliqués après la création de l'enregistrement. Composia appelle l'API Cloudflare pour modifier chaque enregistrement DNS avec le statut de proxy et le commentaire demandés.
+
+Les fournisseurs autres que Cloudflare ne prennent pas en charge ces options. Définir `proxied` ou `comment` avec un autre fournisseur fait échouer la mise à jour DNS.
+
+## Mise en correspondance des zones
+
+Composia met en correspondance le nom d'hôte du service avec les zones configurées. Les zones sont essayées de la correspondance la plus longue à la plus courte. Par exemple, avec `zones: ["example.com.", "sub.example.com."]`, le nom d'hôte `app.sub.example.com` correspond d'abord à `sub.example.com.`.
+
+Si aucune zone ne correspond au nom d'hôte, la mise à jour DNS échoue.
+
+## Nettoyage des enregistrements obsolètes
+
+La synchronisation DNS gère exactement trois types d'enregistrements par nom d'hôte : A, AAAA et CNAME. Tout type d'enregistrement configuré qui n'est pas présent dans l'état souhaité est supprimé avant que les nouveaux enregistrements ne soient définis. Par exemple, si un service avait précédemment `record_type: A` et passe à `record_type: CNAME`, l'ancien enregistrement A est supprimé et un nouvel enregistrement CNAME est créé.
+
+Changer le nom d'hôte d'un service ne nettoie pas les enregistrements de l'ancien nom d'hôte. Si vous renommez `app.example.com` en `api.example.com`, les enregistrements pour `app.example.com` restent chez le fournisseur DNS jusqu'à ce que vous les supprimiez manuellement.
diff --git a/site/content/docs/guide/dns.ja.md b/site/content/docs/guide/dns.ja.md
new file mode 100644
index 0000000..bc64e95
--- /dev/null
+++ b/site/content/docs/guide/dns.ja.md
@@ -0,0 +1,125 @@
+---
+title: "DNS"
+date: '2026-05-26T00:00:00+08:00'
+weight: 20
+---
+
+Composia は `network.dns` を宣言したサービスの DNS レコードを管理します。DNS 更新はコントローラー側のタスクとして実行されます。
+
+## 動作の仕組み
+
+サービスがデプロイされるか、DNS 更新が手動でトリガーされると、コントローラーは `dns_update` タスクを作成します。コントローラーワーカーがそれを実行します:
+
+1. タスクに記録されたリポジトリリビジョンでサービスメタを読み取ります。
+2. `network.dns` から期待する DNS レコードを構築します。
+3. レコードを DNS プロバイダーに同期します。
+
+## プロバイダー設定
+
+コントローラー設定で少なくとも 1 つの DNS プロバイダーを設定します。プロバイダーの認証情報とゾーンリストはグローバルです:
+
+```yaml
+controller:
+ dns:
+ cloudflare:
+ api_token: "REPLACE"
+ zones:
+ - "example.com"
+ - "other.com"
+```
+
+5 つのプロバイダーがサポートされています。それぞれ固有の認証情報キーを持ち、管理対象ドメインゾーンをリストする `zones` フィールドを共有します:
+
+| プロバイダー | キープレフィックス | 認証情報キー |
+|----------|-----------|-----------------|
+| `cloudflare` | `dns.cloudflare` | `api_token`, `api_token_file` |
+| `alidns` | `dns.alidns` | `access_key_id`, `access_key_secret`, `region_id`, オプション `security_token` |
+| `dnspod` | `dns.dnspod` | `secret_id`, `secret_key`, `region`, オプション `session_token` |
+| `route53` | `dns.route53` | `access_key_id`, `secret_access_key`, `region`, オプション `session_token`, `profile`, `hosted_zone_id` |
+| `huaweicloud` | `dns.huaweicloud` | `access_key_id`, `secret_access_key`, `region_id` |
+
+各認証情報フィールドには、ファイルから読み取るための対応する `_file` バリアントがあります（例: `api_token_file`）。
+
+## サービス DNS 宣言
+
+サービスの `composia-meta.yaml` で DNS 設定を宣言します:
+
+```yaml
+network:
+ dns:
+ provider: cloudflare
+ hostname: app.example.com
+ record_type: A
+ value: 203.0.113.10
+ proxied: true
+ ttl: 120
+ comment: "Managed by Composia"
+```
+
+| キー | 型 | 必須 | 説明 |
+|-----|------|----------|-------------|
+| `provider` | `string` | はい | `cloudflare`、`alidns`、`dnspod`、`route53`、`huaweicloud` のいずれか。 |
+| `hostname` | `string` | はい | DNS ホスト名。ゾーンは設定されたゾーンリストからマッチングされます。 |
+| `record_type` | `string` | いいえ | `A`、`AAAA`、`CNAME`。空の場合、レコードタイプは値またはノードアドレスから推論されます。 |
+| `value` | `string` | いいえ | 明示的な DNS レコード値。空の場合、Composia はターゲットノードから値を導出します。 |
+| `proxied` | `bool` | いいえ | Cloudflare プロキシを有効にします。Cloudflare のみ対応。 |
+| `ttl` | `uint32` | いいえ | DNS TTL（秒単位）。 |
+| `comment` | `string` | いいえ | DNS レコードコメント。Cloudflare のみ対応。 |
+
+## レコード解決
+
+### 明示的な値の場合
+
+`value` が設定されている場合、Composia はそれを直接使用します。IP アドレスの場合、レコードタイプが推論されます: IPv4 は `A`、IPv6 は `AAAA` になります。ホスト名の場合、レコードタイプは `CNAME` である必要があります（空の場合も `CNAME` に解決されます）。
+
+```yaml
+network:
+ dns:
+ provider: cloudflare
+ hostname: app.example.com
+ value: 203.0.113.10
+```
+
+### ノードアドレスから解決
+
+`value` が空の場合、Composia はコントローラー設定のターゲットノードの `public_ipv4` と `public_ipv6` を使用します:
+
+```yaml
+controller:
+ nodes:
+ - id: "main"
+ public_ipv4: "203.0.113.10"
+ public_ipv6: "2001:db8::10"
+```
+
+`record_type` が空の場合、ノードが両方のアドレスを持つときに A レコードと AAAA レコードの両方が作成されます。`record_type` が `A` の場合、IPv4 アドレスのみが使用されます。`record_type` が `AAAA` の場合、IPv6 アドレスのみが使用されます。
+
+複数のノードをターゲットとするサービスは `value` を明示的に設定する必要があります。複数のターゲットノードがある場合に `value` が空だとエラーになります。
+
+## DNS 更新のトリガー
+
+DNS レコードはデプロイタスクフロー中に作成または更新されます。Web UI または CLI から独立した DNS 更新をトリガーすることもできます:
+
+```bash
+composia service dns-update my-app
+```
+
+これは `dns_update` タスクを作成します。タスクログにはゾーン解決、レコード操作、最終結果が表示されます。
+
+## Cloudflare オプション
+
+プロバイダーが `cloudflare` の場合、`proxied` と `comment` はレコード作成後に適用されます。Composia は Cloudflare API を呼び出して各 DNS レコードを要求されたプロキシステータスとコメントでパッチします。
+
+Cloudflare 以外のプロバイダーはこれらのオプションをサポートしていません。他のプロバイダーで `proxied` または `comment` を設定すると DNS 更新が失敗します。
+
+## ゾーンマッチング
+
+Composia はサービスホスト名を設定されたゾーンと照合します。ゾーンは最も長い一致から最も短い一致の順に試行されます。例えば `zones: ["example.com.", "sub.example.com."]` の場合、ホスト名 `app.sub.example.com` は最初に `sub.example.com.` にマッチします。
+
+ホスト名に一致するゾーンがない場合、DNS 更新は失敗します。
+
+## 古いレコードのクリーンアップ
+
+DNS 同期はホスト名ごとにちょうど 3 つのレコードタイプ（A、AAAA、CNAME）を管理します。期待状態に存在しない設定済みレコードタイプは、新しいレコードが設定される前に削除されます。例えば、以前 `record_type: A` だったサービスが `record_type: CNAME` に変更された場合、古い A レコードが削除され新しい CNAME レコードが作成されます。
+
+サービスのホスト名を変更しても、古いホスト名のレコードはクリーンアップされません。`app.example.com` を `api.example.com` にリネームした場合、`app.example.com` のレコードは手動で削除するまで DNS プロバイダーに残ります。
diff --git a/site/content/docs/guide/dns.zh-hans.md b/site/content/docs/guide/dns.zh-hans.md
new file mode 100644
index 0000000..deafd4c
--- /dev/null
+++ b/site/content/docs/guide/dns.zh-hans.md
@@ -0,0 +1,125 @@
+---
+title: "DNS"
+date: '2026-05-26T00:00:00+08:00'
+weight: 20
+---
+
+Composia 为声明了 `network.dns` 的服务管理 DNS 记录。DNS 更新作为控制器端的任务运行。
+
+## 工作原理
+
+当服务部署或手动触发 DNS 更新时，控制器会创建一个 `dns_update` 任务。控制器工作线程执行它：
+
+1. 读取任务中记录的仓库版本下的服务元数据。
+2. 从 `network.dns` 构建期望的 DNS 记录。
+3. 将记录同步到 DNS 提供商。
+
+## 提供商配置
+
+在控制器配置中配置至少一个 DNS 提供商。提供商凭据和区域列表是全局的：
+
+```yaml
+controller:
+ dns:
+ cloudflare:
+ api_token: "REPLACE"
+ zones:
+ - "example.com"
+ - "other.com"
+```
+
+支持五种提供商。每种都有自己的凭据键，并且都共享一个列出托管域区域的 `zones` 字段：
+
+| 提供商 | 键前缀 | 凭据键 |
+|----------|-----------|-----------------|
+| `cloudflare` | `dns.cloudflare` | `api_token`、`api_token_file` |
+| `alidns` | `dns.alidns` | `access_key_id`、`access_key_secret`、`region_id`，可选 `security_token` |
+| `dnspod` | `dns.dnspod` | `secret_id`、`secret_key`、`region`，可选 `session_token` |
+| `route53` | `dns.route53` | `access_key_id`、`secret_access_key`、`region`，可选 `session_token`、`profile`、`hosted_zone_id` |
+| `huaweicloud` | `dns.huaweicloud` | `access_key_id`、`secret_access_key`、`region_id` |
+
+每个凭据字段都有对应的 `_file` 变体，用于从文件中读取（例如 `api_token_file`）。
+
+## 服务 DNS 声明
+
+在服务的 `composia-meta.yaml` 中声明 DNS 设置：
+
+```yaml
+network:
+ dns:
+ provider: cloudflare
+ hostname: app.example.com
+ record_type: A
+ value: 203.0.113.10
+ proxied: true
+ ttl: 120
+ comment: "由 Composia 管理"
+```
+
+| 键 | 类型 | 必填 | 描述 |
+|-----|------|----------|-------------|
+| `provider` | `string` | 是 | `cloudflare`、`alidns`、`dnspod`、`route53` 或 `huaweicloud`。 |
+| `hostname` | `string` | 是 | DNS 主机名。区域从已配置的区域列表中匹配。 |
+| `record_type` | `string` | 否 | `A`、`AAAA` 或 `CNAME`。为空时，根据值或节点地址推断。 |
+| `value` | `string` | 否 | 显式的 DNS 记录值。为空时，Composia 从目标节点派生值。 |
+| `proxied` | `bool` | 否 | 启用 Cloudflare 代理。仅 Cloudflare 支持。 |
+| `ttl` | `uint32` | 否 | DNS TTL，单位为秒。 |
+| `comment` | `string` | 否 | DNS 记录备注。仅 Cloudflare 支持。 |
+
+## 记录解析
+
+### 使用显式值
+
+当设置了 `value` 时，Composia 直接使用它。如果是 IP 地址，记录类型会被推断：IPv4 为 `A`，IPv6 为 `AAAA`。如果是主机名，记录类型必须为 `CNAME`（或留空，同样解析为 `CNAME`）。
+
+```yaml
+network:
+ dns:
+ provider: cloudflare
+ hostname: app.example.com
+ value: 203.0.113.10
+```
+
+### 从节点地址解析
+
+当 `value` 为空时，Composia 使用控制器配置中目标节点的 `public_ipv4` 和 `public_ipv6`：
+
+```yaml
+controller:
+ nodes:
+ - id: "main"
+ public_ipv4: "203.0.113.10"
+ public_ipv6: "2001:db8::10"
+```
+
+当 `record_type` 为空时，如果节点同时拥有两种地址，则会创建 A 和 AAAA 记录。如果 `record_type` 为 `A`，则仅使用 IPv4 地址。如果 `record_type` 为 `AAAA`，则仅使用 IPv6 地址。
+
+目标多个节点的服务必须显式设置 `value`。在多目标节点且 `value` 为空的情况下会产生错误。
+
+## 触发 DNS 更新
+
+DNS 记录在部署任务流程中创建或更新。您也可以通过 Web UI 或 CLI 触发独立的 DNS 更新：
+
+```bash
+composia service dns-update my-app
+```
+
+这会创建一个 `dns_update` 任务。任务日志显示区域解析、记录操作和最终结果。
+
+## Cloudflare 选项
+
+当提供商为 `cloudflare` 时，`proxied` 和 `comment` 在记录创建后生效。Composia 调用 Cloudflare API 为每个 DNS 记录设置代理状态和备注。
+
+非 Cloudflare 提供商不支持这些选项。在其他提供商上设置 `proxied` 或 `comment` 会导致 DNS 更新失败。
+
+## 区域匹配
+
+Composia 将服务主机名与已配置的区域进行匹配。区域按从最长到最短的顺序尝试匹配。例如，对于 `zones: ["example.com.", "sub.example.com."]`，主机名 `app.sub.example.com` 会首先匹配 `sub.example.com.`。
+
+如果没有区域匹配到主机名，DNS 更新将失败。
+
+## 过期记录清理
+
+DNS 同步管理每个主机名的恰好三种记录类型：A、AAAA 和 CNAME。在设置新记录之前，任何不在期望状态中的已配置记录类型都会被删除。例如，如果某个服务之前使用 `record_type: A`，后来改为 `record_type: CNAME`，则旧的 A 记录会被删除，新的 CNAME 记录会被创建。
+
+更改服务的主机名不会清理旧主机名的记录。如果您将 `app.example.com` 重命名为 `api.example.com`，`app.example.com` 的记录会保留在 DNS 提供商中，直到您手动删除。
diff --git a/site/content/docs/guide/dns.zh-hant.md b/site/content/docs/guide/dns.zh-hant.md
new file mode 100644
index 0000000..4c092a0
--- /dev/null
+++ b/site/content/docs/guide/dns.zh-hant.md
@@ -0,0 +1,125 @@
+---
+title: "DNS"
+date: '2026-05-26T00:00:00+08:00'
+weight: 20
+---
+
+Composia 管理宣告 `network.dns` 的服務的 DNS 記錄。DNS 更新以控制器端任務的形式執行。
+
+## 運作方式
+
+當服務部署完成或手動觸發 DNS 更新時，控制器會建立一個 `dns_update` 任務。控制器工作器執行該任務：
+
+1. 讀取任務中記錄的存放庫修訂版本中的服務中繼資料。
+2. 從 `network.dns` 建置期望的 DNS 記錄。
+3. 將記錄同步到 DNS 提供者。
+
+## 提供者設定
+
+在控制器設定中至少設定一個 DNS 提供者。提供者憑證與區域清單是全域的：
+
+```yaml
+controller:
+ dns:
+ cloudflare:
+ api_token: "REPLACE"
+ zones:
+ - "example.com"
+ - "other.com"
+```
+
+支援五種提供者。每個都有各自的憑證鍵，並共用一個列出受管網域區域的 `zones` 欄位：
+
+| 提供者 | 鍵前綴 | 憑證鍵 |
+|----------|-----------|-----------------|
+| `cloudflare` | `dns.cloudflare` | `api_token`、`api_token_file` |
+| `alidns` | `dns.alidns` | `access_key_id`、`access_key_secret`、`region_id`、可選 `security_token` |
+| `dnspod` | `dns.dnspod` | `secret_id`、`secret_key`、`region`、可選 `session_token` |
+| `route53` | `dns.route53` | `access_key_id`、`secret_access_key`、`region`、可選 `session_token`、`profile`、`hosted_zone_id` |
+| `huaweicloud` | `dns.huaweicloud` | `access_key_id`、`secret_access_key`、`region_id` |
+
+每個憑證欄位都有對應的 `_file` 變體，用於從檔案讀取（例如 `api_token_file`）。
+
+## 服務 DNS 宣告
+
+在服務的 `composia-meta.yaml` 中宣告 DNS 設定：
+
+```yaml
+network:
+ dns:
+ provider: cloudflare
+ hostname: app.example.com
+ record_type: A
+ value: 203.0.113.10
+ proxied: true
+ ttl: 120
+ comment: "Managed by Composia"
+```
+
+| 鍵 | 型別 | 必要 | 說明 |
+|-----|------|----------|-------------|
+| `provider` | `string` | 是 | `cloudflare`、`alidns`、`dnspod`、`route53` 或 `huaweicloud`。 |
+| `hostname` | `string` | 是 | DNS 主機名稱。區域從已設定的區域清單中進行比對。 |
+| `record_type` | `string` | 否 | `A`、`AAAA` 或 `CNAME`。為空白時，記錄型別從值或節點位址推斷。 |
+| `value` | `string` | 否 | 明確的 DNS 記錄值。為空白時，Composia 從目標節點衍生該值。 |
+| `proxied` | `bool` | 否 | 啟用 Cloudflare 代理。僅 Cloudflare 支援。 |
+| `ttl` | `uint32` | 否 | DNS TTL，以秒為單位。 |
+| `comment` | `string` | 否 | DNS 記錄備註。僅 Cloudflare 支援。 |
+
+## 記錄解析
+
+### 使用明確的值
+
+當設定 `value` 時，Composia 直接使用它。如果它是 IP 位址，則記錄型別會被推斷：IPv4 為 `A`，IPv6 為 `AAAA`。如果它是主機名稱，記錄型別必須為 `CNAME`（或空白，同樣會解析為 `CNAME`）。
+
+```yaml
+network:
+ dns:
+ provider: cloudflare
+ hostname: app.example.com
+ value: 203.0.113.10
+```
+
+### 從節點位址
+
+當 `value` 為空白時，Composia 使用控制器設定中目標節點的 `public_ipv4` 和 `public_ipv6`：
+
+```yaml
+controller:
+ nodes:
+ - id: "main"
+ public_ipv4: "203.0.113.10"
+ public_ipv6: "2001:db8::10"
+```
+
+當 `record_type` 為空白且節點同時擁有兩個位址時，會建立 A 和 AAAA 兩筆記錄。若 `record_type` 為 `A`，則僅使用 IPv4 位址。若 `record_type` 為 `AAAA`，則僅使用 IPv6 位址。
+
+目標超過一個節點的服務必須明確設定 `value`。多目標節點但 `value` 為空白會產生錯誤。
+
+## 觸發 DNS 更新
+
+DNS 記錄在部署任務流程中建立或更新。您也可以透過 Web UI 或 CLI 觸發獨立的 DNS 更新：
+
+```bash
+composia service dns-update my-app
+```
+
+這會建立一個 `dns_update` 任務。任務日誌會顯示區域解析、記錄操作與最終結果。
+
+## Cloudflare 選項
+
+當提供者為 `cloudflare` 時，`proxied` 和 `comment` 會在記錄建立後套用。Composia 會呼叫 Cloudflare API 以要求的代理狀態和備註修補每個 DNS 記錄。
+
+非 Cloudflare 提供者不支援這些選項。對其他提供者設定 `proxied` 或 `comment` 會導致 DNS 更新失敗。
+
+## 區域比對
+
+Composia 將服務主機名稱與已設定的區域進行比對。區域從最長到最短的匹配順序嘗試。例如，使用 `zones: ["example.com.", "sub.example.com."]` 時，主機名稱 `app.sub.example.com` 會先匹配 `sub.example.com.`。
+
+若沒有任何區域匹配主機名稱，則 DNS 更新失敗。
+
+## 過期記錄清理
+
+DNS 同步精確管理每個主機名稱的三種記錄型別：A、AAAA 和 CNAME。在設定新記錄之前，會先刪除期望狀態中不存在的任何已設定記錄型別。例如，如果服務先前有 `record_type: A` 而後改為 `record_type: CNAME`，則舊的 A 記錄會被移除並建立新的 CNAME 記錄。
+
+變更服務的主機名稱不會清理舊主機名稱的記錄。如果您將 `app.example.com` 改名為 `api.example.com`，`app.example.com` 的記錄會保留在 DNS 提供者中，直到您手動移除為止。
diff --git a/site/content/docs/guide/image-updates.de.md b/site/content/docs/guide/image-updates.de.md
new file mode 100644
index 0000000..77c1449
--- /dev/null
+++ b/site/content/docs/guide/image-updates.de.md
@@ -0,0 +1,199 @@
+---
+title: "Image-Updates"
+date: '2026-05-26T00:00:00+08:00'
+weight: 60
+---
+
+Composia erkennt neue Image-Tags und kann Updates automatisch anwenden. Image-Check-Aufgaben laufen auf dem Agenten und melden die Ergebnisse an den Controller.
+
+## Wie es funktioniert
+
+Der Controller plant regelmäßige `image_check`-Aufgaben gemäß der Update-Konfiguration des Dienstes. Jede Prüfung:
+
+1. Der Agent lädt das Dienstpaket herunter.
+2. Liest `docker compose config --format json`, um laufende Images zu erkennen.
+3. Meldet lokale und entfernte Digests für jedes Image.
+4. Für Images, die in `update.images` konfiguriert sind, prüft es auf neue Kandidaten-Tags unter Verwendung der konfigurierten Erkennungsquellen.
+5. Meldet die Ergebnisse an den Controller. Der Controller zeichnet verfügbare Updates auf und kann sie automatisch anwenden.
+
+## Controller-Standardwerte
+
+Globale Standardwerte werden in der Controller-Konfiguration gesetzt:
+
+```yaml
+controller:
+ updates:
+ default_check_schedule: "0 */6 * * *"
+ auto_apply: false
+ backup_before_update: true
+ digest_pin: false
+ semver:
+ default_allow:
+ - patch
+ - minor
+ forge_auth:
+ github:
+ url: "https://github.com"
+ token: "REPLACE"
+ api_url: "https://api.github.com"
+```
+
+Der dienstspezifische `update`-Abschnitt überschreibt diese Standardwerte.
+
+## Dienstkonfiguration
+
+```yaml
+update:
+ enabled: true
+ auto_apply: false
+ check_schedule: "0 */6 * * *"
+ backup_before_update: true
+ digest_pin: false
+ backup_data:
+ - name: db
+ enabled: true
+ discovery_sources:
+ upstream-gh:
+ sources:
+ - type: github
+ repo: owner/repo
+ combine: first_success
+ include_prerelease: false
+ images:
+ api:
+ image: ghcr.io/example/api
+ current:
+ env:
+ file: .env
+ key: API_VERSION
+ discovery: upstream-gh
+ filter:
+ type: semver
+ allow:
+ - patch
+ - minor
+```
+
+### `update` oberste Ebene
+
+| Schlüssel | Typ | Beschreibung |
+|-----|------|-------------|
+| `enabled` | `bool` | Aktiviert Update-Prüfungen für diesen Dienst. |
+| `auto_apply` | `bool` | Wendet erkannte Updates automatisch an. |
+| `check_schedule` | `string` | Cron-Zeitplan für Update-Prüfungen. |
+| `backup_before_update` | `bool` | Führt ein Backup vor dem Anwenden eines Updates aus. |
+| `backup_data` | `[]object` | Geschützte Datenelemente, die vor dem Update gesichert werden sollen. Jedes Element hat einen `name` und optional `enabled`. |
+| `digest_pin` | `bool` | Fixiert Images per Digest für Reproduzierbarkeit. |
+| `discovery_sources` | `map[string]object` | Benannte wiederverwendbare Erkennungskonfigurationen. |
+| `images` | `map[string]object` | Update-Konfiguration pro Image. Schlüssel sind beliebige Namen, die den zu prüfenden Images entsprechen. |
+
+### `images.`
+
+| Schlüssel | Typ | Erforderlich | Beschreibung |
+|-----|------|----------|-------------|
+| `image` | `string` | Ja | Vollständige Image-Referenz, zum Beispiel `ghcr.io/example/api`. |
+| `auto_apply` | `bool` | Nein | Per-Image-Override für automatisches Anwenden. |
+| `check_schedule` | `string` | Nein | Per-Image-Prüfzeitplan. |
+| `backup_before_update` | `bool` | Nein | Per-Image-Backup-Umschalter. |
+| `digest_pin` | `bool` | Nein | Per-Image-Digest-Pin-Umschalter. |
+| `current` | `object` | Ja | Wie die aktuell deployte Version gefunden wird. |
+| `discovery` | `object` oder `string` | Ja | Erkennungskonfiguration oder Verweis auf einen benannten `discovery_sources`-Eintrag. |
+| `filter` | `object` | Bed. | Versionsfilter. Erforderlich, es sei denn, der Erkennungsmodus ist `digest`. |
+
+### `current`
+
+Genau eine dieser Quellen muss angegeben werden:
+
+**Statischer Tag:**
+
+```yaml
+current:
+ tag: "v1.2.3"
+```
+
+**Umgebungsdatei:**
+
+```yaml
+current:
+ env:
+ file: .env
+ key: APP_VERSION
+```
+
+Der `file`-Pfad ist relativ zum Dienstverzeichnis. Composia liest die Datei, sucht nach `SCHLÜSSEL=WERT`-Zeilen und extrahiert den Wert.
+
+**YAML-Datei:**
+
+```yaml
+current:
+ yaml:
+ file: values.yaml
+ path: app.image.tag
+```
+
+Der `path` ist ein durch Punkte getrennter Pfad in den YAML-Dokumentbaum. Der Wert an diesem Pfad muss ein Skalar sein.
+
+### Erkennung
+
+Erkennungsquellen können sein:
+
+**Benannte Referenz** auf einen `discovery_sources`-Eintrag:
+
+```yaml
+discovery: upstream-gh
+```
+
+**Inline-Definition:**
+
+```yaml
+discovery:
+ sources:
+ - type: probe
+ combine: first_success
+ include_prerelease: false
+```
+
+Erkennungsquellentypen:
+
+| Typ | Erforderliche Schlüssel | Verhalten |
+|------|---------------|----------|
+| `probe` | Keine | Semver-Sondierung: Sucht nach höheren Versionen durch Sondieren von Registry-Manifesten. Erfordert einen `semver`-Filter. |
+| `registry` | Keine | Listet alle Tags aus der Image-Registry auf. |
+| `auto` | Keine (optional `repo_url`) | Versucht `probe`, dann `registry` als zusammengeführte Erkennung. Muss die einzige Quelle in einer Erkennungskonfiguration sein. |
+| `digest` | Keine | Vergleicht nur den entfernten Digest mit dem lokalen Digest. Kein Tag-Vergleich. `filter` muss weggelassen werden. Muss die einzige Quelle sein. |
+| `github` | `repo` (`owner/repo`) | Fragt GitHub-Releases ab. Wird auf der Controller-Seite verarbeitet. |
+| `gitlab` | `project` | Fragt GitLab-Releases ab. Wird auf der Controller-Seite verarbeitet. |
+| `forgejo` | `repo` (`owner/repo`) | Fragt Forgejo-Releases ab. Wird auf der Controller-Seite verarbeitet. |
+
+`combine` akzeptiert `merge` (Vereinigung aller Quellergebnisse) oder `first_success` (erste Quelle, die Ergebnisse liefert, gewinnt).
+
+`include_prerelease` schließt Vorabversionen in GitHub-, GitLab- und Forgejo-Release-Abfragen ein.
+
+### Filter
+
+| Typ | Erforderliche Schlüssel | Verhalten |
+|------|---------------|----------|
+| `semver` | Keine | Filtert nach semantischer Version. `allow` kann `patch`, `minor`, `major` enthalten. |
+| `date` | `format` | Parst Tags als Daten mit dem angegebenen Format. |
+| `regex` | `pattern`, `order` | Filtert nach Regex. Order muss `numeric` oder `lexicographic` sein. |
+| `latest` | Keine | Nimmt den neuesten Tag ohne Filterung. |
+
+#### Semver-Sondierung
+
+Mit `type: probe` und einem `semver`-Filter sucht Composia nach Kandidaten-Tags, indem es Versionsnummern konstruiert und prüft, ob das entsprechende Registry-Manifest existiert. Es sondiert Patch-, Minor- und Major-Sprünge gemäß der `allow`-Liste unter Verwendung einer exponentiellen Suche mit binärer Verfeinerung, um die höchste verfügbare Version zu finden.
+
+## Digest-Modus
+
+Wenn alle Erkennungsquellen in einer Konfiguration `type: digest` haben, wird kein Tag-Vergleich durchgeführt. Composia vergleicht nur den entfernten Image-Digest mit dem lokalen Digest:
+
+```yaml
+discovery:
+ sources:
+ - type: digest
+```
+
+Wenn `digest` als Erkennungsmodus gesetzt ist, muss `filter` weggelassen werden. Wenn ein Digest abweicht, wird ein Update als verfügbar betrachtet.
+
+## Image-Beobachtungen
+
+Während Deploy- und Update-Aufgaben sammelt der Agent auch Image-Beobachtungen für alle Compose-Dienste. Diese umfassen lokale und entfernte Digests, die unabhängig davon an den Controller gemeldet werden, ob `update.images` konfiguriert ist. Dies bietet Einblick in den Image-Zustand in der Web-UI und CLI.
diff --git a/site/content/docs/guide/image-updates.fr.md b/site/content/docs/guide/image-updates.fr.md
new file mode 100644
index 0000000..897abbf
--- /dev/null
+++ b/site/content/docs/guide/image-updates.fr.md
@@ -0,0 +1,199 @@
+---
+title: "Mises à jour d'images"
+date: '2026-05-26T00:00:00+08:00'
+weight: 60
+---
+
+Composia détecte les nouvelles balises d'images et peut appliquer les mises à jour automatiquement. Les tâches de vérification d'images s'exécutent sur l'agent et rapportent les résultats au contrôleur.
+
+## Fonctionnement
+
+Le contrôleur planifie des tâches `image_check` périodiques selon la configuration de mise à jour du service. Chaque vérification :
+
+1. L'agent télécharge le bundle de service.
+2. Lit `docker compose config --format json` pour découvrir les images en cours d'exécution.
+3. Rapporte les empreintes locales et distantes pour chaque image.
+4. Pour les images configurées dans `update.images`, vérifie les nouvelles balises candidates en utilisant les sources de découverte configurées.
+5. Rapporte les résultats au contrôleur. Le contrôleur enregistre les mises à jour disponibles et peut les appliquer automatiquement.
+
+## Valeurs par défaut du contrôleur
+
+Les valeurs par défaut globales sont définies dans la configuration du contrôleur :
+
+```yaml
+controller:
+ updates:
+ default_check_schedule: "0 */6 * * *"
+ auto_apply: false
+ backup_before_update: true
+ digest_pin: false
+ semver:
+ default_allow:
+ - patch
+ - minor
+ forge_auth:
+ github:
+ url: "https://github.com"
+ token: "REPLACE"
+ api_url: "https://api.github.com"
+```
+
+La section `update` au niveau du service remplace ces valeurs par défaut.
+
+## Configuration du service
+
+```yaml
+update:
+ enabled: true
+ auto_apply: false
+ check_schedule: "0 */6 * * *"
+ backup_before_update: true
+ digest_pin: false
+ backup_data:
+ - name: db
+ enabled: true
+ discovery_sources:
+ upstream-gh:
+ sources:
+ - type: github
+ repo: owner/repo
+ combine: first_success
+ include_prerelease: false
+ images:
+ api:
+ image: ghcr.io/example/api
+ current:
+ env:
+ file: .env
+ key: API_VERSION
+ discovery: upstream-gh
+ filter:
+ type: semver
+ allow:
+ - patch
+ - minor
+```
+
+### `update` niveau supérieur
+
+| Clé | Type | Description |
+|-----|------|-------------|
+| `enabled` | `bool` | Active les vérifications de mise à jour pour ce service. |
+| `auto_apply` | `bool` | Applique automatiquement les mises à jour détectées. |
+| `check_schedule` | `string` | Planification cron pour les vérifications de mise à jour. |
+| `backup_before_update` | `bool` | Exécute une sauvegarde avant d'appliquer une mise à jour. |
+| `backup_data` | `[]object` | Éléments de données protégés à sauvegarder avant la mise à jour. Chaque élément a un `name` et un `enabled` optionnel. |
+| `digest_pin` | `bool` | Épingler les images par empreinte pour la reproductibilité. |
+| `discovery_sources` | `map[string]object` | Configurations de découverte nommées réutilisables. |
+| `images` | `map[string]object` | Configuration de mise à jour par image. Les clés sont des noms arbitraires correspondant aux images à vérifier. |
+
+### `images.`
+
+| Clé | Type | Requis | Description |
+|-----|------|----------|-------------|
+| `image` | `string` | Oui | Référence complète de l'image, par exemple `ghcr.io/example/api`. |
+| `auto_apply` | `bool` | Non | Remplacement auto-apply par image. |
+| `check_schedule` | `string` | Non | Planification de vérification par image. |
+| `backup_before_update` | `bool` | Non | Activation de la sauvegarde par image. |
+| `digest_pin` | `bool` | Non | Activation de l'épinglage par empreinte par image. |
+| `current` | `object` | Oui | Comment trouver la version actuellement déployée. |
+| `discovery` | `object` ou `string` | Oui | Configuration de découverte ou référence à une entrée nommée `discovery_sources`. |
+| `filter` | `object` | Cond. | Filtre de version. Requis sauf si le mode de découverte est `digest`. |
+
+### `current`
+
+Exactement une de ces sources doit être spécifiée :
+
+**Balise statique :**
+
+```yaml
+current:
+ tag: "v1.2.3"
+```
+
+**Fichier d'environnement :**
+
+```yaml
+current:
+ env:
+ file: .env
+ key: APP_VERSION
+```
+
+Le chemin `file` est relatif au répertoire du service. Composia lit le fichier, cherche les lignes `CLE=VALEUR` et extrait la valeur.
+
+**Fichier YAML :**
+
+```yaml
+current:
+ yaml:
+ file: values.yaml
+ path: app.image.tag
+```
+
+Le `path` est un chemin séparé par des points dans l'arborescence du document YAML. La valeur à ce chemin doit être un scalaire.
+
+### Découverte
+
+Les sources de découverte peuvent être :
+
+**Référence nommée** vers une entrée `discovery_sources` :
+
+```yaml
+discovery: upstream-gh
+```
+
+**Définition en ligne :**
+
+```yaml
+discovery:
+ sources:
+ - type: probe
+ combine: first_success
+ include_prerelease: false
+```
+
+Types de sources de découverte :
+
+| Type | Clés requises | Comportement |
+|------|---------------|----------|
+| `probe` | Aucune | Sondage semver : recherche les versions supérieures en sondant les manifestes du registre. Nécessite un filtre `semver`. |
+| `registry` | Aucune | Liste toutes les balises du registre d'images. |
+| `auto` | Aucune (`repo_url` optionnel) | Essaie `probe` puis `registry` comme découverte fusionnée. Doit être la seule source dans une configuration de découverte. |
+| `digest` | Aucune | Compare uniquement l'empreinte distante avec l'empreinte locale. Pas de comparaison de balises. `filter` doit être omis. Doit être la seule source. |
+| `github` | `repo` (`owner/repo`) | Interroge les releases GitHub. Traité côté contrôleur. |
+| `gitlab` | `project` | Interroge les releases GitLab. Traité côté contrôleur. |
+| `forgejo` | `repo` (`owner/repo`) | Interroge les releases Forgejo. Traité côté contrôleur. |
+
+`combine` accepte `merge` (union de tous les résultats des sources) ou `first_success` (la première source qui retourne des résultats gagne).
+
+`include_prerelease` inclut les versions préliminaires dans les requêtes de releases GitHub, GitLab et Forgejo.
+
+### Filtre
+
+| Type | Clés requises | Comportement |
+|------|---------------|----------|
+| `semver` | Aucune | Filtrer par version sémantique. `allow` peut contenir `patch`, `minor`, `major`. |
+| `date` | `format` | Analyser les balises comme des dates en utilisant le format donné. |
+| `regex` | `pattern`, `order` | Filtrer par expression régulière. `order` doit être `numeric` ou `lexicographic`. |
+| `latest` | Aucune | Prendre la dernière balise sans filtrer. |
+
+#### Sondage semver
+
+Avec `type: probe` et un filtre `semver`, Composia recherche les balises candidates en construisant des numéros de version et en vérifiant si le manifeste du registre correspondant existe. Il sonde les incréments patch, minor et major selon la liste `allow`, en utilisant une recherche exponentielle avec raffinement binaire pour trouver la version disponible la plus élevée.
+
+## Mode empreinte
+
+Lorsque toutes les sources de découverte dans une configuration ont `type: digest`, aucune comparaison de balises n'est effectuée. Composia compare uniquement l'empreinte de l'image distante avec l'empreinte locale :
+
+```yaml
+discovery:
+ sources:
+ - type: digest
+```
+
+Lorsque `digest` est défini comme mode de découverte, `filter` doit être omis. Si une empreinte diffère, une mise à jour est considérée comme disponible.
+
+## Observations d'images
+
+Pendant les tâches de déploiement et de mise à jour, l'agent collecte également des observations d'images pour tous les services Compose. Celles-ci incluent les empreintes locales et distantes, rapportées au contrôleur indépendamment de la présence de `update.images`. Cela fournit une visibilité sur l'état des images dans l'interface web et la CLI.
diff --git a/site/content/docs/guide/image-updates.ja.md b/site/content/docs/guide/image-updates.ja.md
new file mode 100644
index 0000000..f7b11b2
--- /dev/null
+++ b/site/content/docs/guide/image-updates.ja.md
@@ -0,0 +1,199 @@
+---
+title: "イメージ更新"
+date: '2026-05-26T00:00:00+08:00'
+weight: 60
+---
+
+Composia は新しいイメージタグを検出し、更新を自動的に適用できます。イメージチェックタスクはエージェント上で実行され、結果をコントローラーに報告します。
+
+## 動作の仕組み
+
+コントローラーはサービスの更新設定に従って定期的な `image_check` タスクをスケジュールします。各チェックは:
+
+1. エージェントがサービスバンドルをダウンロードします。
+2. `docker compose config --format json` を読み取って実行中のイメージを検出します。
+3. 各イメージのローカルとリモートのダイジェストを報告します。
+4. `update.images` で設定されたイメージについて、設定された検出ソースを使用して新しい候補タグをチェックします。
+5. 結果をコントローラーに報告します。コントローラーは利用可能な更新を記録し、自動適用できます。
+
+## コントローラーデフォルト
+
+グローバルデフォルトはコントローラー設定で設定します:
+
+```yaml
+controller:
+ updates:
+ default_check_schedule: "0 */6 * * *"
+ auto_apply: false
+ backup_before_update: true
+ digest_pin: false
+ semver:
+ default_allow:
+ - patch
+ - minor
+ forge_auth:
+ github:
+ url: "https://github.com"
+ token: "REPLACE"
+ api_url: "https://api.github.com"
+```
+
+サービスレベルの `update` セクションがこれらのデフォルトを上書きします。
+
+## サービス設定
+
+```yaml
+update:
+ enabled: true
+ auto_apply: false
+ check_schedule: "0 */6 * * *"
+ backup_before_update: true
+ digest_pin: false
+ backup_data:
+ - name: db
+ enabled: true
+ discovery_sources:
+ upstream-gh:
+ sources:
+ - type: github
+ repo: owner/repo
+ combine: first_success
+ include_prerelease: false
+ images:
+ api:
+ image: ghcr.io/example/api
+ current:
+ env:
+ file: .env
+ key: API_VERSION
+ discovery: upstream-gh
+ filter:
+ type: semver
+ allow:
+ - patch
+ - minor
+```
+
+### `update` トップレベル
+
+| キー | 型 | 説明 |
+|-----|------|-------------|
+| `enabled` | `bool` | このサービスの更新チェックを有効にします。 |
+| `auto_apply` | `bool` | 検出された更新を自動的に適用します。 |
+| `check_schedule` | `string` | 更新チェックの cron スケジュール。 |
+| `backup_before_update` | `bool` | 更新を適用する前にバックアップを実行します。 |
+| `backup_data` | `[]object` | 更新前にバックアップする保護データ項目。各項目は `name` とオプションの `enabled` を持ちます。 |
+| `digest_pin` | `bool` | 再現性のためにイメージをダイジェストで固定します。 |
+| `discovery_sources` | `map[string]object` | 名前付きの再利用可能な検出設定。 |
+| `images` | `map[string]object` | イメージごとの更新設定。キーはチェックするイメージに一致する任意の名前です。 |
+
+### `images.`
+
+| キー | 型 | 必須 | 説明 |
+|-----|------|----------|-------------|
+| `image` | `string` | はい | 完全なイメージ参照（例: `ghcr.io/example/api`）。 |
+| `auto_apply` | `bool` | いいえ | イメージごとの自動適用の上書き。 |
+| `check_schedule` | `string` | いいえ | イメージごとのチェックスケジュール。 |
+| `backup_before_update` | `bool` | いいえ | イメージごとのバックアップトグル。 |
+| `digest_pin` | `bool` | いいえ | イメージごとのダイジェスト固定トグル。 |
+| `current` | `object` | はい | 現在デプロイされているバージョンの見つけ方。 |
+| `discovery` | `object` または `string` | はい | 検出設定または名前付き `discovery_sources` エントリへの参照。 |
+| `filter` | `object` | 条件付き | バージョンフィルター。検出モードが `digest` でない限り必須。 |
+
+### `current`
+
+以下のいずれか 1 つを指定する必要があります:
+
+**静的タグ:**
+
+```yaml
+current:
+ tag: "v1.2.3"
+```
+
+**環境ファイル:**
+
+```yaml
+current:
+ env:
+ file: .env
+ key: APP_VERSION
+```
+
+`file` パスはサービスディレクトリからの相対パスです。Composia はファイルを読み取り、`KEY=VALUE` 行を探して値を抽出します。
+
+**YAML ファイル:**
+
+```yaml
+current:
+ yaml:
+ file: values.yaml
+ path: app.image.tag
+```
+
+`path` は YAML ドキュメントツリー内のドット区切りパスです。そのパスの値はスカラーである必要があります。
+
+### 検出
+
+検出ソースには以下があります:
+
+**名前付き参照**（`discovery_sources` エントリへの参照）:
+
+```yaml
+discovery: upstream-gh
+```
+
+**インライン定義:**
+
+```yaml
+discovery:
+ sources:
+ - type: probe
+ combine: first_success
+ include_prerelease: false
+```
+
+検出ソースタイプ:
+
+| タイプ | 必須キー | 動作 |
+|------|---------------|----------|
+| `probe` | なし | Semver プロービング: レジストリマニフェストをプローブしてより高いバージョンを検索します。`semver` フィルターが必要です。 |
+| `registry` | なし | イメージレジストリからすべてのタグをリストします。 |
+| `auto` | なし（オプション `repo_url`） | マージされた検出として `probe` を試し、その後 `registry` を試します。検出設定内で唯一のソースである必要があります。 |
+| `digest` | なし | リモートダイジェストとローカルダイジェストのみを比較します。タグ比較は行いません。`filter` は省略する必要があります。唯一のソースである必要があります。 |
+| `github` | `repo`（`owner/repo`） | GitHub リリースをクエリします。コントローラー側で処理されます。 |
+| `gitlab` | `project` | GitLab リリースをクエリします。コントローラー側で処理されます。 |
+| `forgejo` | `repo`（`owner/repo`） | Forgejo リリースをクエリします。コントローラー側で処理されます。 |
+
+`combine` は `merge`（すべてのソース結果の和集合）または `first_success`（結果を返した最初のソースが優先）を受け付けます。
+
+`include_prerelease` は GitHub、GitLab、Forgejo のリリースクエリにプレリリースバージョンを含めます。
+
+### フィルター
+
+| タイプ | 必須キー | 動作 |
+|------|---------------|----------|
+| `semver` | なし | セマンティックバージョンでフィルター。`allow` には `patch`、`minor`、`major` を含められます。 |
+| `date` | `format` | 指定されたフォーマットを使用してタグを日付として解析します。 |
+| `regex` | `pattern`, `order` | 正規表現でフィルター。`order` は `numeric` または `lexicographic` である必要があります。 |
+| `latest` | なし | フィルターなしで最新のタグを取得します。 |
+
+#### Semver プロービング
+
+`type: probe` と `semver` フィルターを使用すると、Composia はバージョン番号を構築し、対応するレジストリマニフェストが存在するかをチェックして候補タグを検索します。`allow` リストに従って patch、minor、major のバンプをプローブし、指数的検索とバイナリ絞り込みを使用して利用可能な最高バージョンを見つけます。
+
+## ダイジェストモード
+
+設定内のすべての検出ソースが `type: digest` の場合、タグ比較は行われません。Composia はリモートイメージダイジェストをローカルダイジェストと比較するだけです:
+
+```yaml
+discovery:
+ sources:
+ - type: digest
+```
+
+検出モードとして `digest` が設定されている場合、`filter` は省略する必要があります。ダイジェストが異なる場合、更新が利用可能と見なされます。
+
+## イメージオブザベーション
+
+デプロイおよび更新タスク中、エージェントはすべての compose サービスのイメージオブザベーションも収集します。これにはローカルとリモートのダイジェストが含まれ、`update.images` が設定されているかどうかに関わらずコントローラーに報告されます。これにより Web UI と CLI でイメージ状態の可視性が提供されます。
diff --git a/site/content/docs/guide/image-updates.zh-hans.md b/site/content/docs/guide/image-updates.zh-hans.md
new file mode 100644
index 0000000..328a4c3
--- /dev/null
+++ b/site/content/docs/guide/image-updates.zh-hans.md
@@ -0,0 +1,199 @@
+---
+title: "镜像更新"
+date: '2026-05-26T00:00:00+08:00'
+weight: 60
+---
+
+Composia 检测新的镜像标签并可以自动应用更新。镜像检查任务在 agent 上运行，并将发现结果上报给控制器。
+
+## 工作原理
+
+控制器根据服务的更新配置调度定期的 `image_check` 任务。每次检查：
+
+1. Agent 下载服务包。
+2. 读取 `docker compose config --format json` 以发现正在运行的镜像。
+3. 上报每个镜像的本地和远程摘要。
+4. 对于在 `update.images` 中配置的镜像，使用配置的发现源检查新的候选标签。
+5. 将结果上报给控制器。控制器记录可用的更新并可自动应用它们。
+
+## 控制器默认值
+
+全局默认值在控制器配置中设置：
+
+```yaml
+controller:
+ updates:
+ default_check_schedule: "0 */6 * * *"
+ auto_apply: false
+ backup_before_update: true
+ digest_pin: false
+ semver:
+ default_allow:
+ - patch
+ - minor
+ forge_auth:
+ github:
+ url: "https://github.com"
+ token: "REPLACE"
+ api_url: "https://api.github.com"
+```
+
+服务级别的 `update` 部分会覆盖这些默认值。
+
+## 服务配置
+
+```yaml
+update:
+ enabled: true
+ auto_apply: false
+ check_schedule: "0 */6 * * *"
+ backup_before_update: true
+ digest_pin: false
+ backup_data:
+ - name: db
+ enabled: true
+ discovery_sources:
+ upstream-gh:
+ sources:
+ - type: github
+ repo: owner/repo
+ combine: first_success
+ include_prerelease: false
+ images:
+ api:
+ image: ghcr.io/example/api
+ current:
+ env:
+ file: .env
+ key: API_VERSION
+ discovery: upstream-gh
+ filter:
+ type: semver
+ allow:
+ - patch
+ - minor
+```
+
+### `update` 顶级键
+
+| 键 | 类型 | 描述 |
+|-----|------|-------------|
+| `enabled` | `bool` | 为此服务启用更新检查。 |
+| `auto_apply` | `bool` | 自动应用检测到的更新。 |
+| `check_schedule` | `string` | 更新检查的 cron 计划。 |
+| `backup_before_update` | `bool` | 在应用更新之前运行备份。 |
+| `backup_data` | `[]object` | 更新前要备份的受保护数据项。每个项有 `name` 和可选的 `enabled`。 |
+| `digest_pin` | `bool` | 通过摘要锁定镜像以提高可重复性。 |
+| `discovery_sources` | `map[string]object` | 命名的可复用发现配置。 |
+| `images` | `map[string]object` | 每镜像更新配置。键是与要检查的镜像匹配的任意名称。 |
+
+### `images.`
+
+| 键 | 类型 | 必填 | 描述 |
+|-----|------|----------|-------------|
+| `image` | `string` | 是 | 完整镜像引用，例如 `ghcr.io/example/api`。 |
+| `auto_apply` | `bool` | 否 | 每镜像自动应用覆盖。 |
+| `check_schedule` | `string` | 否 | 每镜像检查计划。 |
+| `backup_before_update` | `bool` | 否 | 每镜像备份开关。 |
+| `digest_pin` | `bool` | 否 | 每镜像摘要锁定开关。 |
+| `current` | `object` | 是 | 如何找到当前部署的版本。 |
+| `discovery` | `object` 或 `string` | 是 | 发现配置或对命名 `discovery_sources` 条目的引用。 |
+| `filter` | `object` | 条件 | 版本过滤器。除非发现模式为 `digest`，否则必填。 |
+
+### `current`
+
+必须指定以下来源之一：
+
+**静态标签：**
+
+```yaml
+current:
+ tag: "v1.2.3"
+```
+
+**环境文件：**
+
+```yaml
+current:
+ env:
+ file: .env
+ key: APP_VERSION
+```
+
+`file` 路径相对于服务目录。Composia 读取文件，查找 `KEY=VALUE` 行并提取值。
+
+**YAML 文件：**
+
+```yaml
+current:
+ yaml:
+ file: values.yaml
+ path: app.image.tag
+```
+
+`path` 是进入 YAML 文档树的点分隔路径。该路径处的值必须为标量。
+
+### 发现
+
+发现源可以是：
+
+**命名引用**，指向 `discovery_sources` 条目：
+
+```yaml
+discovery: upstream-gh
+```
+
+**内联定义：**
+
+```yaml
+discovery:
+ sources:
+ - type: probe
+ combine: first_success
+ include_prerelease: false
+```
+
+发现源类型：
+
+| 类型 | 必填键 | 行为 |
+|------|---------------|----------|
+| `probe` | 无 | 语义化版本探测：通过探测注册表清单搜索更高版本。需要 `semver` 过滤器。 |
+| `registry` | 无 | 列出镜像注册表中的所有标签。 |
+| `auto` | 无（可选 `repo_url`） | 作为合并发现，先尝试 `probe` 再尝试 `registry`。必须是发现配置中的唯一源。 |
+| `digest` | 无 | 仅比较远程摘要与本地摘要。不进行标签比较。必须省略 `filter`。必须是唯一源。 |
+| `github` | `repo`（`owner/repo`） | 查询 GitHub 发布。在控制器端处理。 |
+| `gitlab` | `project` | 查询 GitLab 发布。在控制器端处理。 |
+| `forgejo` | `repo`（`owner/repo`） | 查询 Forgejo 发布。在控制器端处理。 |
+
+`combine` 接受 `merge`（所有源结果的并集）或 `first_success`（第一个返回结果的源胜出）。
+
+`include_prerelease` 在 GitHub、GitLab 和 Forgejo 发布查询中包含预发布版本。
+
+### 过滤器
+
+| 类型 | 必填键 | 行为 |
+|------|---------------|----------|
+| `semver` | 无 | 按语义化版本过滤。`allow` 可包含 `patch`、`minor`、`major`。 |
+| `date` | `format` | 使用给定的格式将标签解析为日期。 |
+| `regex` | `pattern`、`order` | 按正则表达式过滤。`order` 必须为 `numeric` 或 `lexicographic`。 |
+| `latest` | 无 | 取最新标签，不进行过滤。 |
+
+#### 语义化版本探测
+
+使用 `type: probe` 和 `semver` 过滤器时，Composia 通过构造版本号并检查相应注册表清单是否存在来搜索候选标签。它根据 `allow` 列表探测补丁（patch）、次版本（minor）和主版本（major）的升级，使用指数搜索配合二分法精化来找到最高可用版本。
+
+## 摘要模式
+
+当配置中的所有发现源类型均为 `digest` 时，不执行标签比较。Composia 仅将远程镜像摘要与本地摘要进行比较：
+
+```yaml
+discovery:
+ sources:
+ - type: digest
+```
+
+当发现模式设置为 `digest` 时，必须省略 `filter`。如果摘要不同，则认为存在可用更新。
+
+## 镜像观测
+
+在部署和更新任务期间，agent 还会为所有 compose 服务收集镜像观测信息。这些信息包括本地和远程摘要，无论是否配置了 `update.images` 都会上报给控制器。这提供了 Web UI 和 CLI 中的镜像状态可见性。
diff --git a/site/content/docs/guide/image-updates.zh-hant.md b/site/content/docs/guide/image-updates.zh-hant.md
new file mode 100644
index 0000000..8dff044
--- /dev/null
+++ b/site/content/docs/guide/image-updates.zh-hant.md
@@ -0,0 +1,199 @@
+---
+title: "映像檔更新"
+date: '2026-05-26T00:00:00+08:00'
+weight: 60
+---
+
+Composia 偵測新的映像檔標籤並可自動套用更新。映像檔檢查任務在代理端執行並將結果回報給控制器。
+
+## 運作方式
+
+控制器根據服務的更新設定排程週期性的 `image_check` 任務。每次檢查：
+
+1. 代理下載服務包。
+2. 讀取 `docker compose config --format json` 以發現執行中的映像檔。
+3. 回報每個映像檔的本機與遠端摘要。
+4. 對於在 `update.images` 中設定的映像檔，使用已設定的發現來源檢查新的候選標籤。
+5. 將結果回報給控制器。控制器記錄可用的更新並可自動套用。
+
+## 控制器預設值
+
+全域預設值在控制器設定中設定：
+
+```yaml
+controller:
+ updates:
+ default_check_schedule: "0 */6 * * *"
+ auto_apply: false
+ backup_before_update: true
+ digest_pin: false
+ semver:
+ default_allow:
+ - patch
+ - minor
+ forge_auth:
+ github:
+ url: "https://github.com"
+ token: "REPLACE"
+ api_url: "https://api.github.com"
+```
+
+服務層級的 `update` 區段會覆蓋這些預設值。
+
+## 服務設定
+
+```yaml
+update:
+ enabled: true
+ auto_apply: false
+ check_schedule: "0 */6 * * *"
+ backup_before_update: true
+ digest_pin: false
+ backup_data:
+ - name: db
+ enabled: true
+ discovery_sources:
+ upstream-gh:
+ sources:
+ - type: github
+ repo: owner/repo
+ combine: first_success
+ include_prerelease: false
+ images:
+ api:
+ image: ghcr.io/example/api
+ current:
+ env:
+ file: .env
+ key: API_VERSION
+ discovery: upstream-gh
+ filter:
+ type: semver
+ allow:
+ - patch
+ - minor
+```
+
+### `update` 頂層
+
+| 鍵 | 型別 | 說明 |
+|-----|------|-------------|
+| `enabled` | `bool` | 為此服務啟用更新檢查。 |
+| `auto_apply` | `bool` | 自動套用偵測到的更新。 |
+| `check_schedule` | `string` | 更新檢查的 cron 排程。 |
+| `backup_before_update` | `bool` | 在套用更新前執行備份。 |
+| `backup_data` | `[]object` | 更新前要備份的受保護資料項目。每個項目都有 `name` 和可選的 `enabled`。 |
+| `digest_pin` | `bool` | 以摘要固定映像檔，確保可重現性。 |
+| `discovery_sources` | `map[string]object` | 具名的可重用發現設定。 |
+| `images` | `map[string]object` | 每個映像檔的更新設定。鍵為任意名稱，對應要檢查的映像檔。 |
+
+### `images.`
+
+| 鍵 | 型別 | 必要 | 說明 |
+|-----|------|----------|-------------|
+| `image` | `string` | 是 | 完整映像檔引用，例如 `ghcr.io/example/api`。 |
+| `auto_apply` | `bool` | 否 | 每個映像檔的自動套用覆蓋。 |
+| `check_schedule` | `string` | 否 | 每個映像檔的檢查排程。 |
+| `backup_before_update` | `bool` | 否 | 每個映像檔的備份開關。 |
+| `digest_pin` | `bool` | 否 | 每個映像檔的摘要固定開關。 |
+| `current` | `object` | 是 | 如何找到目前部署的版本。 |
+| `discovery` | `object` 或 `string` | 是 | 發現設定或對具名 `discovery_sources` 項目的引用。 |
+| `filter` | `object` | 條件必要 | 版本過濾器。除非發現模式為 `digest`，否則為必要項。 |
+
+### `current`
+
+必須恰好指定以下來源之一：
+
+**靜態標籤：**
+
+```yaml
+current:
+ tag: "v1.2.3"
+```
+
+**環境檔案：**
+
+```yaml
+current:
+ env:
+ file: .env
+ key: APP_VERSION
+```
+
+`file` 路徑相對於服務目錄。Composia 讀取該檔案，尋找 `KEY=VALUE` 行，並提取該值。
+
+**YAML 檔案：**
+
+```yaml
+current:
+ yaml:
+ file: values.yaml
+ path: app.image.tag
+```
+
+`path` 是以點分隔的 YAML 文件樹路徑。該路徑上的值必須為純量。
+
+### 發現
+
+發現來源可以是：
+
+**具名引用**，指向 `discovery_sources` 項目：
+
+```yaml
+discovery: upstream-gh
+```
+
+**內聯定義：**
+
+```yaml
+discovery:
+ sources:
+ - type: probe
+ combine: first_success
+ include_prerelease: false
+```
+
+發現來源型別：
+
+| 型別 | 必要鍵 | 行為 |
+|------|---------------|----------|
+| `probe` | 無 | Semver 探測：透過探測登錄庫清單來搜尋更高版本。需要 `semver` 過濾器。 |
+| `registry` | 無 | 列出映像檔登錄庫中的所有標籤。 |
+| `auto` | 無（可選 `repo_url`） | 嘗試 `probe` 再嘗試 `registry`，作為合併的發現方式。必須是發現設定中的唯一來源。 |
+| `digest` | 無 | 僅比較遠端摘要與本地摘要。不進行標籤比較。必須省略 `filter`。必須是唯一來源。 |
+| `github` | `repo` (`owner/repo`) | 查詢 GitHub 發行版本。在控制器端處理。 |
+| `gitlab` | `project` | 查詢 GitLab 發行版本。在控制器端處理。 |
+| `forgejo` | `repo` (`owner/repo`) | 查詢 Forgejo 發行版本。在控制器端處理。 |
+
+`combine` 接受 `merge`（所有來源結果的聯集）或 `first_success`（首次返回結果的來源獲勝）。
+
+`include_prerelease` 在 GitHub、GitLab 和 Forgejo 的發行版本查詢中包含預發行版本。
+
+### 過濾器
+
+| 型別 | 必要鍵 | 行為 |
+|------|---------------|----------|
+| `semver` | 無 | 按語意化版本過濾。`allow` 可包含 `patch`、`minor`、`major`。 |
+| `date` | `format` | 使用指定的格式將標籤解析為日期。 |
+| `regex` | `pattern`、`order` | 按正則表達式過濾。`order` 必須為 `numeric` 或 `lexicographic`。 |
+| `latest` | 無 | 取最新標籤，不進行過濾。 |
+
+#### Semver 探測
+
+使用 `type: probe` 和 `semver` 過濾器時，Composia 透過構造版本號並檢查對應的登錄庫清單是否存在來搜尋候選標籤。它會根據 `allow` 清單探測修補、次要和主要版本的升級，使用指數搜尋配合二分法精煉，以找到最高可用版本。
+
+## 摘要模式
+
+當設定中的所有發現來源均為 `type: digest` 時，不進行標籤比較。Composia 僅比較遠端映像檔摘要與本地摘要：
+
+```yaml
+discovery:
+ sources:
+ - type: digest
+```
+
+當發現模式設為 `digest` 時，必須省略 `filter`。如果摘要不同，則視為有可用更新。
+
+## 映像檔觀察
+
+在部署和更新任務期間，代理也會收集所有 compose 服務的映像檔觀察。這些包括本地與遠端摘要，無論是否設定了 `update.images` 都會回報給控制器。這提供了 Web UI 和 CLI 中的映像檔狀態可見性。
diff --git a/site/content/docs/guide/migrate.de.md b/site/content/docs/guide/migrate.de.md
new file mode 100644
index 0000000..2779130
--- /dev/null
+++ b/site/content/docs/guide/migrate.de.md
@@ -0,0 +1,94 @@
+---
+title: "Migration"
+date: '2026-05-26T00:00:00+08:00'
+weight: 45
+---
+
+Migriere einen Dienst von einem Node zu einem anderen unter Wahrung der Datenintegrität. Die Migrationsaufgabe orchestriert Backup-, Stopp-, Restore-, Start- und DNS-Update-Schritte über Quell- und Ziel-Nodes hinweg.
+
+## Konfiguration
+
+Datenelemente, die während der Migration übertragen werden, müssen sowohl eine `backup`- als auch eine `restore`-Aktion in `data_protect` haben. Deklariere sie in `migrate`:
+
+```yaml
+name: my-app
+nodes:
+ - main
+
+data_protect:
+ data:
+ - name: uploads
+ backup:
+ strategy: files.copy
+ include:
+ - ./data/uploads
+ restore:
+ strategy: files.copy
+ include:
+ - ./data/uploads
+
+migrate:
+ data:
+ - name: uploads
+```
+
+| Schlüssel | Typ | Erforderlich | Beschreibung |
+|-----|------|----------|-------------|
+| `name` | `string` | Ja | Muss auf einen `data_protect.data[].name` mit sowohl Backup- als auch Restore-Aktionen verweisen. |
+| `enabled` | `bool` | Nein | Aktiviert oder deaktiviert die Migration für dieses Element. |
+
+## Migration ausführen
+
+**Web-UI:**
+1. Öffne die Dienst-Detailseite.
+2. Verwende die Migrationssteuerung, um Quell- und Ziel-Nodes auszuwählen.
+3. Klicke auf **Migrieren**.
+
+**CLI:**
+
+```bash
+composia service migrate my-app --to edge-1
+```
+
+## Migrationsschritte
+
+1. **Daten exportieren** — Führe eine Backup-Aufgabe auf dem Quell-Node für jedes konfigurierte Datenelement aus.
+2. **Quellinstanz stoppen** — Führe `docker compose down` aus, entferne die Caddy-Konfiguration.
+3. **Caddy auf der Quelle neu laden** — Entferne den Proxy-Eintrag von der Quell-Caddy-Instanz.
+4. **Daten auf dem Ziel wiederherstellen** — Führe eine Restore-Aufgabe auf dem Ziel-Node für jedes Datenelement aus.
+5. **Auf dem Ziel deployen** — Führe `docker compose up -d` aus, synchronisiere die Caddy-Konfiguration.
+6. **Caddy auf dem Ziel neu laden** — Wende den Proxy-Eintrag auf der Ziel-Caddy-Instanz an.
+7. **DNS aktualisieren** — Aktualisiere DNS-Records, um auf den Ziel-Node zu verweisen.
+8. **Konfiguration schreiben** — Aktualisiere `nodes` in `composia-meta.yaml`, committe in Git.
+
+## Überlegungen
+
+- Der Dienst muss auf dem Quell-Node deployed sein und der Ziel-Node muss online sein.
+- Die Migration verursacht kurze Ausfallzeiten. Führe sie außerhalb der Spitzenzeiten durch.
+- Die Quellinstanz wird vor der Datenübertragung gestoppt, um Konsistenz zu gewährleisten.
+- Für Datenbanken verwende Exportstrategien (`database.pgdumpall` / `database.pgimport`).
+
+## Rollback
+
+Wenn eine Migration fehlschlägt oder abgelehnt wird, löse eine Rollback-Aufgabe über die Web-UI oder CLI aus. Die Rollback-Aufgabe unterstützt diese Wiederherstellungsaktionen:
+
+| Aktion | Beschreibung |
+|--------|-------------|
+| `deploy_source` | Deploye den Dienst erneut auf dem ursprünglichen Quell-Node. |
+| `stop_target` | Stoppe und bereinige den Dienst auf dem Ziel-Node. |
+| `rollback_dns` | Synchronisiere DNS-Records zurück zum Quell-Node. |
+
+Wähle die Aktionen, die zum fehlgeschlagenen Schritt passen. Wenn die Migration beispielsweise fehlschlug, nachdem das Ziel deployed wurde, aber DNS noch nicht aktualisiert wurde, benötigst du möglicherweise nur `stop_target` und `deploy_source`.
+
+**CLI:**
+
+```bash
+composia task rollback --deploy-source --stop-target --rollback-dns
+```
+
+Lasse Flags für Aktionen weg, die du nicht benötigst.
+
+## Siehe auch
+
+- [Backups](/docs/guide/backups/) — Rustic-Einrichtung und Backup-Konfiguration.
+- [Dienstkonfiguration](/docs/guide/service/) — `data_protect`- und `migrate`-Feldreferenz.
diff --git a/site/content/docs/guide/migrate.fr.md b/site/content/docs/guide/migrate.fr.md
new file mode 100644
index 0000000..0cade55
--- /dev/null
+++ b/site/content/docs/guide/migrate.fr.md
@@ -0,0 +1,94 @@
+---
+title: "Migration"
+date: '2026-05-26T00:00:00+08:00'
+weight: 45
+---
+
+Migrez un service d'un nœud à un autre tout en préservant l'intégrité des données. La tâche de migration orchestre les étapes de sauvegarde, arrêt, restauration, démarrage et mise à jour DNS à travers les nœuds source et cible.
+
+## Configuration
+
+Les éléments de données transportés pendant la migration doivent avoir à la fois une action `backup` et une action `restore` dans `data_protect`. Déclarez-les dans `migrate` :
+
+```yaml
+name: my-app
+nodes:
+ - main
+
+data_protect:
+ data:
+ - name: uploads
+ backup:
+ strategy: files.copy
+ include:
+ - ./data/uploads
+ restore:
+ strategy: files.copy
+ include:
+ - ./data/uploads
+
+migrate:
+ data:
+ - name: uploads
+```
+
+| Clé | Type | Requis | Description |
+|-----|------|----------|-------------|
+| `name` | `string` | Oui | Doit référencer un `data_protect.data[].name` avec les deux actions de sauvegarde et de restauration. |
+| `enabled` | `bool` | Non | Activer ou désactiver la migration pour cet élément. |
+
+## Exécuter la migration
+
+**Interface web :**
+1. Ouvrez la page de détail du service.
+2. Utilisez les contrôles de migration pour sélectionner les nœuds source et cible.
+3. Cliquez sur **Migrate**.
+
+**CLI :**
+
+```bash
+composia service migrate my-app --to edge-1
+```
+
+## Étapes de la migration
+
+1. **Exporter les données** — exécuter une tâche de sauvegarde sur le nœud source pour chaque élément de données configuré.
+2. **Arrêter l'instance source** — exécuter `docker compose down`, supprimer la configuration Caddy.
+3. **Recharger Caddy sur la source** — supprimer l'entrée de proxy de l'instance Caddy source.
+4. **Restaurer les données sur la cible** — exécuter une tâche de restauration sur le nœud cible pour chaque élément de données.
+5. **Déployer sur la cible** — exécuter `docker compose up -d`, synchroniser la configuration Caddy.
+6. **Recharger Caddy sur la cible** — appliquer l'entrée de proxy sur l'instance Caddy cible.
+7. **Mettre à jour le DNS** — mettre à jour les enregistrements DNS pour pointer vers le nœud cible.
+8. **Écrire la configuration** — mettre à jour `nodes` dans `composia-meta.yaml`, commiter dans Git.
+
+## Considérations
+
+- Le service doit être déployé sur le nœud source et le nœud cible doit être en ligne.
+- La migration entraîne une brève interruption de service. Effectuez-la pendant les heures creuses.
+- L'instance source est arrêtée avant le transfert de données pour garantir la cohérence.
+- Pour les bases de données, utilisez les stratégies d'export (`database.pgdumpall` / `database.pgimport`).
+
+## Rollback
+
+Lorsqu'une migration échoue ou est rejetée, déclenchez une tâche de rollback depuis l'interface web ou la CLI. La tâche de rollback prend en charge ces actions de récupération :
+
+| Action | Description |
+|--------|-------------|
+| `deploy_source` | Redéployer le service sur le nœud source d'origine. |
+| `stop_target` | Arrêter et nettoyer le service sur le nœud cible. |
+| `rollback_dns` | Resynchroniser les enregistrements DNS vers le nœud source. |
+
+Sélectionnez les actions qui correspondent à l'étape ayant échoué. Par exemple, si la migration a échoué après le déploiement de la cible mais avant la mise à jour DNS, vous pourriez n'avoir besoin que de `stop_target` et `deploy_source`.
+
+**CLI :**
+
+```bash
+composia task rollback --deploy-source --stop-target --rollback-dns
+```
+
+Omettez les drapeaux pour les actions dont vous n'avez pas besoin.
+
+## Voir aussi
+
+- [Sauvegardes](/docs/guide/backups/) — configuration Rustic et configuration des sauvegardes.
+- [Configuration des services](/docs/guide/service/) — référence des champs `data_protect` et `migrate`.
diff --git a/site/content/docs/guide/migrate.ja.md b/site/content/docs/guide/migrate.ja.md
new file mode 100644
index 0000000..82ee2e2
--- /dev/null
+++ b/site/content/docs/guide/migrate.ja.md
@@ -0,0 +1,94 @@
+---
+title: "移行"
+date: '2026-05-26T00:00:00+08:00'
+weight: 45
+---
+
+データの整合性を保ったまま、あるノードから別のノードにサービスを移行します。移行タスクはソースノードとターゲットノード間でバックアップ、停止、リストア、起動、DNS 更新の各ステップを調整します。
+
+## 設定
+
+移行中に引き継がれるデータ項目は、`data_protect` に `backup` と `restore` の両方のアクションを持つ必要があります。`migrate` で宣言します:
+
+```yaml
+name: my-app
+nodes:
+ - main
+
+data_protect:
+ data:
+ - name: uploads
+ backup:
+ strategy: files.copy
+ include:
+ - ./data/uploads
+ restore:
+ strategy: files.copy
+ include:
+ - ./data/uploads
+
+migrate:
+ data:
+ - name: uploads
+```
+
+| キー | 型 | 必須 | 説明 |
+|-----|------|----------|-------------|
+| `name` | `string` | はい | バックアップとリストアの両方のアクションを持つ `data_protect.data[].name` を参照する必要があります。 |
+| `enabled` | `bool` | いいえ | この項目の移行を有効または無効にします。 |
+
+## 移行の実行
+
+**Web UI:**
+1. サービス詳細ページを開きます。
+2. 移行コントロールを使用してソースノードとターゲットノードを選択します。
+3. **移行** をクリックします。
+
+**CLI:**
+
+```bash
+composia service migrate my-app --to edge-1
+```
+
+## 移行手順
+
+1. **データのエクスポート** — 設定された各データ項目について、ソースノードでバックアップタスクを実行します。
+2. **ソースインスタンスの停止** — `docker compose down` を実行し、Caddy 設定を削除します。
+3. **ソースでの Caddy リロード** — ソース Caddy インスタンスからプロキシエントリを削除します。
+4. **ターゲットでのデータリストア** — 各データ項目について、ターゲットノードでリストアタスクを実行します。
+5. **ターゲットでのデプロイ** — `docker compose up -d` を実行し、Caddy 設定を同期します。
+6. **ターゲットでの Caddy リロード** — ターゲット Caddy インスタンスにプロキシエントリを適用します。
+7. **DNS の更新** — DNS レコードをターゲットノードに向けるよう更新します。
+8. **設定の書き込み** — `composia-meta.yaml` の `nodes` を更新し、Git にコミットします。
+
+## 注意点
+
+- サービスはソースノードにデプロイされている必要があり、ターゲットノードはオンラインである必要があります。
+- 移行には短時間のダウンタイムが発生します。オフピーク時間に実行してください。
+- 整合性を確保するため、データ転送前にソースインスタンスが停止されます。
+- データベースの場合はエクスポート戦略（`database.pgdumpall` / `database.pgimport`）を使用してください。
+
+## ロールバック
+
+移行が失敗したか拒否された場合、Web UI または CLI からロールバックタスクをトリガーします。ロールバックタスクは以下の復旧アクションをサポートします:
+
+| アクション | 説明 |
+|--------|-------------|
+| `deploy_source` | 元のソースノードにサービスを再デプロイします。 |
+| `stop_target` | ターゲットノード上のサービスを停止してクリーンアップします。 |
+| `rollback_dns` | DNS レコードをソースノードに戻します。 |
+
+失敗したステップに一致するアクションを選択します。例えば、ターゲットがデプロイされた後に移行が失敗したが DNS がまだ更新されていない場合、`stop_target` と `deploy_source` だけが必要になるかもしれません。
+
+**CLI:**
+
+```bash
+composia task rollback --deploy-source --stop-target --rollback-dns
+```
+
+必要のないアクションのフラグは省略します。
+
+## 関連項目
+
+- [バックアップ](/docs/guide/backups/) — Rustic のセットアップとバックアップ設定。
+- [サービス設定](/docs/guide/service/) — `data_protect` と `migrate` フィールドリファレンス。
diff --git a/site/content/docs/guide/migrate.zh-hans.md b/site/content/docs/guide/migrate.zh-hans.md
new file mode 100644
index 0000000..0e79ea7
--- /dev/null
+++ b/site/content/docs/guide/migrate.zh-hans.md
@@ -0,0 +1,94 @@
+---
+title: "迁移"
+date: '2026-05-26T00:00:00+08:00'
+weight: 45
+---
+
+将服务从一个节点迁移到另一个节点，同时保持数据完整性。迁移任务协调源节点和目标节点之间的备份、停止、恢复、启动和 DNS 更新步骤。
+
+## 配置
+
+迁移期间携带的数据项必须在 `data_protect` 中同时具有 `backup` 和 `restore` 操作。在 `migrate` 中声明它们：
+
+```yaml
+name: my-app
+nodes:
+ - main
+
+data_protect:
+ data:
+ - name: uploads
+ backup:
+ strategy: files.copy
+ include:
+ - ./data/uploads
+ restore:
+ strategy: files.copy
+ include:
+ - ./data/uploads
+
+migrate:
+ data:
+ - name: uploads
+```
+
+| 键 | 类型 | 必填 | 描述 |
+|-----|------|----------|-------------|
+| `name` | `string` | 是 | 必须引用同时具有备份和恢复操作的 `data_protect.data[].name`。 |
+| `enabled` | `bool` | 否 | 启用或禁用此项的迁移。 |
+
+## 执行迁移
+
+**Web UI：**
+1. 打开服务详情页面。
+2. 使用迁移控件选择源节点和目标节点。
+3. 点击**迁移**。
+
+**CLI：**
+
+```bash
+composia service migrate my-app --to edge-1
+```
+
+## 迁移步骤
+
+1. **导出数据** — 在源节点上为每个已配置的数据项运行备份任务。
+2. **停止源实例** — 运行 `docker compose down`，移除 Caddy 配置。
+3. **在源节点重载 Caddy** — 从源 Caddy 实例中移除代理条目。
+4. **在目标节点恢复数据** — 在目标节点上为每个数据项运行恢复任务。
+5. **在目标节点部署** — 运行 `docker compose up -d`，同步 Caddy 配置。
+6. **在目标节点重载 Caddy** — 在目标 Caddy 实例上应用代理条目。
+7. **更新 DNS** — 更新 DNS 记录以指向目标节点。
+8. **写入配置** — 更新 `composia-meta.yaml` 中的 `nodes`，提交到 Git。
+
+## 注意事项
+
+- 服务必须已部署在源节点上，且目标节点必须在线。
+- 迁移会导致短暂停机。请在低峰时段执行。
+- 源实例在数据传输前会停止以保证一致性。
+- 对于数据库，请使用导出策略（`database.pgdumpall` / `database.pgimport`）。
+
+## 回滚
+
+当迁移失败或被拒绝时，通过 Web UI 或 CLI 触发回滚任务。回滚任务支持以下恢复操作：
+
+| 操作 | 描述 |
+|--------|-------------|
+| `deploy_source` | 在原始源节点上重新部署服务。 |
+| `stop_target` | 停止并清理目标节点上的服务。 |
+| `rollback_dns` | 将 DNS 记录同步回源节点。 |
+
+选择与失败步骤匹配的操作。例如，如果迁移在目标节点部署完成后但 DNS 尚未更新时失败，您可能只需要 `stop_target` 和 `deploy_source`。
+
+**CLI：**
+
+```bash
+composia task rollback --deploy-source --stop-target --rollback-dns
+```
+
+省略您不需要的选项标记。
+
+## 另请参阅
+
+- [备份](/docs/guide/backups/) — Rustic 设置与备份配置。
+- [服务配置](/docs/guide/service/) — `data_protect` 和 `migrate` 字段参考。
diff --git a/site/content/docs/guide/migrate.zh-hant.md b/site/content/docs/guide/migrate.zh-hant.md
new file mode 100644
index 0000000..6b8fb72
--- /dev/null
+++ b/site/content/docs/guide/migrate.zh-hant.md
@@ -0,0 +1,94 @@
+---
+title: "遷移"
+date: '2026-05-26T00:00:00+08:00'
+weight: 45
+---
+
+將服務從一個節點遷移到另一個節點，同時保持資料完整性。遷移任務協調跨來源和目標節點的備份、停止、還原、啟動和 DNS 更新步驟。
+
+## 設定
+
+遷移期間攜帶的資料項目必須在 `data_protect` 中同時具有 `backup` 和 `restore` 操作。在 `migrate` 中宣告它們：
+
+```yaml
+name: my-app
+nodes:
+ - main
+
+data_protect:
+ data:
+ - name: uploads
+ backup:
+ strategy: files.copy
+ include:
+ - ./data/uploads
+ restore:
+ strategy: files.copy
+ include:
+ - ./data/uploads
+
+migrate:
+ data:
+ - name: uploads
+```
+
+| 鍵 | 型別 | 必要 | 說明 |
+|-----|------|----------|-------------|
+| `name` | `string` | 是 | 必須引用同時具有備份和還原操作的 `data_protect.data[].name`。 |
+| `enabled` | `bool` | 否 | 啟用或停用此項目的遷移。 |
+
+## 執行遷移
+
+**Web UI：**
+1. 開啟服務詳細頁面。
+2. 使用遷移控制項選擇來源和目標節點。
+3. 點擊 **遷移**。
+
+**CLI：**
+
+```bash
+composia service migrate my-app --to edge-1
+```
+
+## 遷移步驟
+
+1. **匯出資料** — 在來源節點上為每個已設定的資料項目執行備份任務。
+2. **停止來源執行實例** — 執行 `docker compose down`，移除 Caddy 設定。
+3. **在來源端重新載入 Caddy** — 從來源 Caddy 執行實例中移除代理項目。
+4. **在目標端還原資料** — 在目標節點上為每個資料項目執行還原任務。
+5. **在目標端部署** — 執行 `docker compose up -d`，同步 Caddy 設定。
+6. **在目標端重新載入 Caddy** — 在目標 Caddy 執行實例上套用代理項目。
+7. **更新 DNS** — 更新 DNS 記錄以指向目標節點。
+8. **寫入設定** — 更新 `composia-meta.yaml` 中的 `nodes`，提交到 Git。
+
+## 注意事項
+
+- 服務必須部署在來源節點上，且目標節點必須在線。
+- 遷移會造成短暫停機。請在離峰時段執行。
+- 為確保一致性，資料傳輸前會先停止來源執行實例。
+- 對於資料庫，使用匯出策略（`database.pgdumpall` / `database.pgimport`）。
+
+## 回溯
+
+當遷移失敗或被拒絕時，從 Web UI 或 CLI 觸發回溯任務。回溯任務支援以下復原操作：
+
+| 操作 | 說明 |
+|--------|-------------|
+| `deploy_source` | 在原始來源節點上重新部署服務。 |
+| `stop_target` | 在目標節點上停止並清理服務。 |
+| `rollback_dns` | 將 DNS 記錄同步回來源節點。 |
+
+選擇與失敗步驟匹配的操作。例如，如果遷移在目標端部署後失敗但 DNS 尚未更新，您可能只需要 `stop_target` 和 `deploy_source`。
+
+**CLI：**
+
+```bash
+composia task rollback --deploy-source --stop-target --rollback-dns
+```
+
+不需要的操作可省略旗標。
+
+## 參見
+
+- [備份](/docs/guide/backups/) — Rustic 設定與備份設定。
+- [服務設定](/docs/guide/service/) — `data_protect` 和 `migrate` 欄位參考。
diff --git a/site/content/docs/guide/notifications.de.md b/site/content/docs/guide/notifications.de.md
new file mode 100644
index 0000000..239d720
--- /dev/null
+++ b/site/content/docs/guide/notifications.de.md
@@ -0,0 +1,124 @@
+---
+title: "Benachrichtigungen"
+date: '2026-05-26T00:00:00+08:00'
+weight: 70
+---
+
+Composia sendet Benachrichtigungen für Aufgabenergebnisse, Backup-Ereignisse, Image-Updates und Node-Statusänderungen. Drei Benachrichtigungskanäle werden unterstützt: Alertmanager, SMTP und Telegram.
+
+## Konfiguration
+
+Alle Kanäle werden in der Controller-Konfiguration unter `notifications` konfiguriert:
+
+```yaml
+controller:
+ notifications:
+ alertmanager:
+ enabled: true
+ listen_path: "/api/v1/alerts"
+ smtp:
+ enabled: true
+ host: "smtp.example.com"
+ port: 587
+ encryption: starttls
+ username: "alerts@example.com"
+ password: "REPLACE"
+ from: "alerts@example.com"
+ to:
+ - "admin@example.com"
+ on:
+ - task_failed
+ - backup_failed
+ task_sources:
+ - web
+ - cli
+ telegram:
+ enabled: true
+ bot_token: "REPLACE"
+ chat_id: "REPLACE"
+ on:
+ - task_completed
+```
+
+## Ereignistypen
+
+Die folgenden Benachrichtigungsereignistypen sind verfügbar:
+
+| Ereignis | Auslöser |
+|-------|---------|
+| `task_failed` | Eine Aufgabe endet mit Status `failed`. |
+| `task_cancelled` | Eine Aufgabe wird vor Abschluss abgebrochen. |
+| `task_completed` | Eine Aufgabe wird erfolgreich abgeschlossen. |
+| `task_awaiting_confirmation` | Eine Migrationsaufgabe erreicht den Bestätigungsschritt. |
+| `backup_completed` | Eine Backup-Aufgabe oder ein geplantes Backup wird erfolgreich abgeschlossen. |
+| `backup_failed` | Eine Backup-Aufgabe oder ein Schritt schlägt fehl. |
+| `image_update_available` | Eine Image-Prüfung entdeckt eine neue Version. |
+| `image_update_applied` | Ein Image-Update wird angewendet. |
+| `node_offline` | Ein Node sendet keine Heartbeats mehr. |
+| `node_online` | Ein zuvor offline Node sendet wieder Heartbeats. |
+| `alertmanager_alert` | Eine Alertmanager-Benachrichtigung wird empfangen, wenn der Controller als Alertmanager-Webhook-Empfänger konfiguriert ist. |
+
+Jeder Kanal kann mit der `on`-Liste filtern, welche Ereignistypen er behandeln soll. Eine leere `on`-Liste liefert alle Ereignistypen.
+
+## Aufgabenquellenfilter
+
+SMTP- und Telegram-Kanäle unterstützen die Filterung nach der Quelle, die eine Aufgabe ausgelöst hat:
+
+| Quelle | Beschreibung |
+|--------|-------------|
+| `web` | Aktionen, die über die Web-UI ausgelöst wurden. |
+| `cli` | Aktionen, die über die CLI ausgelöst wurden. |
+| `others` | Andere Quellen. |
+| `schedule` | Geplante Aufgaben (Backups, Wartung). |
+| `system` | Systemgenerierte Aufgaben. |
+| `auto_deploy` | Aufgaben, die durch Auto-Deploy-Trigger generiert wurden. |
+
+Wenn `task_sources` leer ist, werden Benachrichtigungen für alle Quelltypen gesendet.
+
+## Alertmanager
+
+Der Controller betreibt einen eingebetteten Alertmanager-Webhook-Empfänger. Wenn aktiviert, lauscht der Empfänger auf dem konfigurierten Pfad:
+
+```yaml
+alertmanager:
+ enabled: true
+ listen_path: "/api/v1/alerts"
+```
+
+| Schlüssel | Typ | Beschreibung |
+|-----|------|-------------|
+| `enabled` | `bool` | Standardmäßig aktiviert, wenn der Abschnitt existiert. |
+| `listen_path` | `string` | HTTP-Pfad zum Empfangen von Alertmanager-Webhooks. Standardmäßig `/api/v1/alerts`. Muss mit `/` beginnen und darf keine Leerzeichen enthalten. |
+
+Richte deine Alertmanager-Instanz mit dieser Webhook-URL auf die Adresse des Controllers aus. Benachrichtigungen werden gemäß ihren Ereignisfiltern an konfigurierte Benachrichtigungskanäle weitergeleitet.
+
+## SMTP
+
+SMTP liefert Benachrichtigungen per E-Mail:
+
+| Schlüssel | Typ | Erforderlich wenn aktiviert | Beschreibung |
+|-----|------|-----------------------|-------------|
+| `enabled` | `bool` | Nein | Standardmäßig aktiviert, wenn der Abschnitt existiert. |
+| `host` | `string` | Ja | SMTP-Server-Hostname. |
+| `port` | `int` | Ja | SMTP-Port. Muss zwischen 1 und 65535 liegen. |
+| `encryption` | `string` | Nein | `none`, `starttls` oder `ssl_tls`. Standardmäßig `starttls`. |
+| `username` | `string` | Nein | SMTP-Authentifizierungs-Benutzername. |
+| `password` | `string` | Nein | SMTP-Passwort. |
+| `password_file` | `string` | Nein | Passwort aus einer Datei lesen. |
+| `from` | `string` | Ja | Absenderadresse. |
+| `to` | `[]string` | Ja | Empfängeradressen. |
+| `on` | `[]string` | Nein | Ereignistypen, für die benachrichtigt werden soll. |
+| `task_sources` | `[]string` | Nein | Aufgabenquellenfilter. |
+
+## Telegram
+
+Telegram sendet Benachrichtigungen über einen Bot an einen Chat:
+
+| Schlüssel | Typ | Erforderlich wenn aktiviert | Beschreibung |
+|-----|------|-----------------------|-------------|
+| `enabled` | `bool` | Nein | Standardmäßig aktiviert, wenn der Abschnitt existiert. |
+| `bot_token` | `string` | Ja | Telegram-Bot-Token von BotFather. |
+| `bot_token_file` | `string` | Nein | Bot-Token aus einer Datei lesen. |
+| `chat_id` | `string` | Ja | Ziel-Chat-ID. |
+| `on` | `[]string` | Nein | Ereignistypen, für die benachrichtigt werden soll. |
+| `task_sources` | `[]string` | Nein | Aufgabenquellenfilter. |
diff --git a/site/content/docs/guide/notifications.fr.md b/site/content/docs/guide/notifications.fr.md
new file mode 100644
index 0000000..5137ceb
--- /dev/null
+++ b/site/content/docs/guide/notifications.fr.md
@@ -0,0 +1,124 @@
+---
+title: "Notifications"
+date: '2026-05-26T00:00:00+08:00'
+weight: 70
+---
+
+Composia envoie des notifications pour les résultats de tâches, les événements de sauvegarde, les mises à jour d'images et les changements d'état des nœuds. Trois canaux de notification sont pris en charge : Alertmanager, SMTP et Telegram.
+
+## Configuration
+
+Tous les canaux sont configurés dans la configuration du contrôleur sous `notifications` :
+
+```yaml
+controller:
+ notifications:
+ alertmanager:
+ enabled: true
+ listen_path: "/api/v1/alerts"
+ smtp:
+ enabled: true
+ host: "smtp.example.com"
+ port: 587
+ encryption: starttls
+ username: "alerts@example.com"
+ password: "REPLACE"
+ from: "alerts@example.com"
+ to:
+ - "admin@example.com"
+ on:
+ - task_failed
+ - backup_failed
+ task_sources:
+ - web
+ - cli
+ telegram:
+ enabled: true
+ bot_token: "REPLACE"
+ chat_id: "REPLACE"
+ on:
+ - task_completed
+```
+
+## Types d'événements
+
+Les types d'événements de notification suivants sont disponibles :
+
+| Événement | Déclencheur |
+|-------|---------|
+| `task_failed` | Une tâche se termine avec le statut `failed`. |
+| `task_cancelled` | Une tâche est annulée avant la fin. |
+| `task_completed` | Une tâche se termine avec succès. |
+| `task_awaiting_confirmation` | Une tâche de migration atteint l'étape de confirmation. |
+| `backup_completed` | Une tâche de sauvegarde ou une sauvegarde planifiée se termine avec succès. |
+| `backup_failed` | Une tâche ou une étape de sauvegarde échoue. |
+| `image_update_available` | Une vérification d'image découvre une nouvelle version. |
+| `image_update_applied` | Une mise à jour d'image est appliquée. |
+| `node_offline` | Un nœud cesse d'envoyer des heartbeats. |
+| `node_online` | Un nœud précédemment hors ligne reprend les heartbeats. |
+| `alertmanager_alert` | Une alerte Alertmanager est reçue lorsque le contrôleur est configuré comme récepteur de webhook Alertmanager. |
+
+Chaque canal peut filtrer les types d'événements qu'il doit traiter en utilisant la liste `on`. Une liste `on` vide délivre tous les types d'événements.
+
+## Filtres de source de tâche
+
+Les canaux SMTP et Telegram prennent en charge le filtrage par la source qui a déclenché une tâche :
+
+| Source | Description |
+|--------|-------------|
+| `web` | Actions déclenchées via l'interface web. |
+| `cli` | Actions déclenchées via la CLI. |
+| `others` | Autres sources. |
+| `schedule` | Tâches planifiées (sauvegardes, maintenance). |
+| `system` | Tâches générées par le système. |
+| `auto_deploy` | Tâches générées par les déclencheurs de déploiement automatique. |
+
+Lorsque `task_sources` est vide, les notifications sont envoyées pour tous les types de sources.
+
+## Alertmanager
+
+Le contrôleur exécute un récepteur de webhook Alertmanager intégré. Lorsqu'il est activé, le récepteur écoute sur le chemin configuré :
+
+```yaml
+alertmanager:
+ enabled: true
+ listen_path: "/api/v1/alerts"
+```
+
+| Clé | Type | Description |
+|-----|------|-------------|
+| `enabled` | `bool` | Activé par défaut lorsque la section existe. |
+| `listen_path` | `string` | Chemin HTTP pour recevoir les webhooks Alertmanager. Par défaut `/api/v1/alerts`. Doit commencer par `/` et ne pas contenir d'espaces. |
+
+Pointez votre instance Alertmanager vers l'adresse du contrôleur avec cette URL de webhook. Les alertes sont transmises aux canaux de notification configurés selon leurs filtres d'événements.
+
+## SMTP
+
+SMTP délivre les notifications par e-mail :
+
+| Clé | Type | Requis si activé | Description |
+|-----|------|-----------------------|-------------|
+| `enabled` | `bool` | Non | Activé par défaut lorsque la section existe. |
+| `host` | `string` | Oui | Nom d'hôte du serveur SMTP. |
+| `port` | `int` | Oui | Port SMTP. Doit être entre 1 et 65535. |
+| `encryption` | `string` | Non | `none`, `starttls` ou `ssl_tls`. Par défaut `starttls`. |
+| `username` | `string` | Non | Nom d'utilisateur d'authentification SMTP. |
+| `password` | `string` | Non | Mot de passe SMTP. |
+| `password_file` | `string` | Non | Lire le mot de passe depuis un fichier. |
+| `from` | `string` | Oui | Adresse de l'expéditeur. |
+| `to` | `[]string` | Oui | Adresses des destinataires. |
+| `on` | `[]string` | Non | Types d'événements pour lesquels notifier. |
+| `task_sources` | `[]string` | Non | Filtres de source de tâche. |
+
+## Telegram
+
+Telegram envoie des notifications à une discussion via un bot :
+
+| Clé | Type | Requis si activé | Description |
+|-----|------|-----------------------|-------------|
+| `enabled` | `bool` | Non | Activé par défaut lorsque la section existe. |
+| `bot_token` | `string` | Oui | Jeton du bot Telegram depuis BotFather. |
+| `bot_token_file` | `string` | Non | Lire le jeton du bot depuis un fichier. |
+| `chat_id` | `string` | Oui | ID de la discussion cible. |
+| `on` | `[]string` | Non | Types d'événements pour lesquels notifier. |
+| `task_sources` | `[]string` | Non | Filtres de source de tâche. |
diff --git a/site/content/docs/guide/notifications.ja.md b/site/content/docs/guide/notifications.ja.md
new file mode 100644
index 0000000..45402e5
--- /dev/null
+++ b/site/content/docs/guide/notifications.ja.md
@@ -0,0 +1,124 @@
+---
+title: "通知"
+date: '2026-05-26T00:00:00+08:00'
+weight: 70
+---
+
+Composia はタスク結果、バックアップイベント、イメージ更新、ノード状態変化の通知を送信します。Alertmanager、SMTP、Telegram の 3 つの通知チャンネルがサポートされています。
+
+## 設定
+
+すべてのチャンネルはコントローラー設定の `notifications` で設定します:
+
+```yaml
+controller:
+ notifications:
+ alertmanager:
+ enabled: true
+ listen_path: "/api/v1/alerts"
+ smtp:
+ enabled: true
+ host: "smtp.example.com"
+ port: 587
+ encryption: starttls
+ username: "alerts@example.com"
+ password: "REPLACE"
+ from: "alerts@example.com"
+ to:
+ - "admin@example.com"
+ on:
+ - task_failed
+ - backup_failed
+ task_sources:
+ - web
+ - cli
+ telegram:
+ enabled: true
+ bot_token: "REPLACE"
+ chat_id: "REPLACE"
+ on:
+ - task_completed
+```
+
+## イベントタイプ
+
+以下の通知イベントタイプが利用可能です:
+
+| イベント | トリガー |
+|-------|---------|
+| `task_failed` | タスクが `failed` ステータスで終了した場合。 |
+| `task_cancelled` | タスクが完了前にキャンセルされた場合。 |
+| `task_completed` | タスクが正常に完了した場合。 |
+| `task_awaiting_confirmation` | 移行タスクが確認ステップに到達した場合。 |
+| `backup_completed` | バックアップタスクまたはスケジュールバックアップが正常に完了した場合。 |
+| `backup_failed` | バックアップタスクまたはステップが失敗した場合。 |
+| `image_update_available` | イメージチェックが新しいバージョンを検出した場合。 |
+| `image_update_applied` | イメージ更新が適用された場合。 |
+| `node_offline` | ノードがハートビートの送信を停止した場合。 |
+| `node_online` | 以前オフラインだったノードがハートビートを再開した場合。 |
+| `alertmanager_alert` | コントローラーが Alertmanager webhook レシーバーとして設定されている場合に Alertmanager アラートを受信した場合。 |
+
+各チャンネルは `on` リストを使用して処理するイベントタイプをフィルタリングできます。空の `on` リストはすべてのイベントタイプを配信します。
+
+## タスクソースフィルター
+
+SMTP と Telegram チャンネルはタスクをトリガーしたソースによるフィルタリングをサポートします:
+
+| ソース | 説明 |
+|--------|-------------|
+| `web` | Web UI を通じてトリガーされたアクション。 |
+| `cli` | CLI を通じてトリガーされたアクション。 |
+| `others` | その他のソース。 |
+| `schedule` | スケジュールされたタスク（バックアップ、メンテナンス）。 |
+| `system` | システム生成タスク。 |
+| `auto_deploy` | 自動デプロイトリガーによって生成されたタスク。 |
+
+`task_sources` が空の場合、すべてのソースタイプに対して通知が送信されます。
+
+## Alertmanager
+
+コントローラーは組み込みの Alertmanager webhook レシーバーを実行します。有効にすると、レシーバーは設定されたパスで待機します:
+
+```yaml
+alertmanager:
+ enabled: true
+ listen_path: "/api/v1/alerts"
+```
+
+| キー | 型 | 説明 |
+|-----|------|-------------|
+| `enabled` | `bool` | セクションが存在する場合、デフォルトで有効。 |
+| `listen_path` | `string` | Alertmanager webhook を受信する HTTP パス。デフォルトは `/api/v1/alerts`。`/` で始まり、空白を含まない必要があります。 |
+
+この webhook URL で Alertmanager インスタンスをコントローラーのアドレスに向けます。アラートはイベントフィルターに従って設定された通知チャンネルに転送されます。
+
+## SMTP
+
+SMTP はメールで通知を配信します:
+
+| キー | 型 | 有効時に必須 | 説明 |
+|-----|------|-----------------------|-------------|
+| `enabled` | `bool` | いいえ | セクションが存在する場合、デフォルトで有効。 |
+| `host` | `string` | はい | SMTP サーバーホスト名。 |
+| `port` | `int` | はい | SMTP ポート。1 から 65535 の間である必要があります。 |
+| `encryption` | `string` | いいえ | `none`、`starttls`、`ssl_tls`。デフォルトは `starttls`。 |
+| `username` | `string` | いいえ | SMTP 認証ユーザー名。 |
+| `password` | `string` | いいえ | SMTP パスワード。 |
+| `password_file` | `string` | いいえ | ファイルからパスワードを読み取ります。 |
+| `from` | `string` | はい | 送信者アドレス。 |
+| `to` | `[]string` | はい | 受信者アドレス。 |
+| `on` | `[]string` | いいえ | 通知するイベントタイプ。 |
+| `task_sources` | `[]string` | いいえ | タスクソースフィルター。 |
+
+## Telegram
+
+Telegram はボットを通じてチャットに通知を送信します:
+
+| キー | 型 | 有効時に必須 | 説明 |
+|-----|------|-----------------------|-------------|
+| `enabled` | `bool` | いいえ | セクションが存在する場合、デフォルトで有効。 |
+| `bot_token` | `string` | はい | BotFather からの Telegram ボットトークン。 |
+| `bot_token_file` | `string` | いいえ | ファイルからボットトークンを読み取ります。 |
+| `chat_id` | `string` | はい | ターゲットチャット ID。 |
+| `on` | `[]string` | いいえ | 通知するイベントタイプ。 |
+| `task_sources` | `[]string` | いいえ | タスクソースフィルター。 |
diff --git a/site/content/docs/guide/notifications.zh-hans.md b/site/content/docs/guide/notifications.zh-hans.md
new file mode 100644
index 0000000..3140b50
--- /dev/null
+++ b/site/content/docs/guide/notifications.zh-hans.md
@@ -0,0 +1,124 @@
+---
+title: "通知"
+date: '2026-05-26T00:00:00+08:00'
+weight: 70
+---
+
+Composia 为任务结果、备份事件、镜像更新和节点状态变化发送通知。支持三种通知渠道：Alertmanager、SMTP 和 Telegram。
+
+## 配置
+
+所有渠道均在控制器配置的 `notifications` 下进行配置：
+
+```yaml
+controller:
+ notifications:
+ alertmanager:
+ enabled: true
+ listen_path: "/api/v1/alerts"
+ smtp:
+ enabled: true
+ host: "smtp.example.com"
+ port: 587
+ encryption: starttls
+ username: "alerts@example.com"
+ password: "REPLACE"
+ from: "alerts@example.com"
+ to:
+ - "admin@example.com"
+ on:
+ - task_failed
+ - backup_failed
+ task_sources:
+ - web
+ - cli
+ telegram:
+ enabled: true
+ bot_token: "REPLACE"
+ chat_id: "REPLACE"
+ on:
+ - task_completed
+```
+
+## 事件类型
+
+以下通知事件类型可用：
+
+| 事件 | 触发条件 |
+|-------|---------|
+| `task_failed` | 任何任务以 `failed` 状态结束。 |
+| `task_cancelled` | 任务在完成前被取消。 |
+| `task_completed` | 任务成功完成。 |
+| `task_awaiting_confirmation` | 迁移任务到达确认步骤。 |
+| `backup_completed` | 备份任务或定时备份成功完成。 |
+| `backup_failed` | 备份任务或步骤失败。 |
+| `image_update_available` | 镜像检查发现新版本。 |
+| `image_update_applied` | 镜像更新已应用。 |
+| `node_offline` | 节点停止发送心跳。 |
+| `node_online` | 之前离线的节点恢复心跳。 |
+| `alertmanager_alert` | 控制器作为 Alertmanager webhook 接收器时收到告警。 |
+
+每个渠道可以通过 `on` 列表过滤应处理的事件类型。空的 `on` 列表表示接收所有事件类型。
+
+## 任务来源过滤器
+
+SMTP 和 Telegram 渠道支持按触发任务来源进行过滤：
+
+| 来源 | 描述 |
+|--------|-------------|
+| `web` | 通过 Web UI 触发的操作。 |
+| `cli` | 通过 CLI 触发的操作。 |
+| `others` | 其他来源。 |
+| `schedule` | 调度的任务（备份、维护）。 |
+| `system` | 系统生成的任务。 |
+| `auto_deploy` | 自动部署触发器生成的任务。 |
+
+当 `task_sources` 为空时，所有来源类型都会发送通知。
+
+## Alertmanager
+
+控制器运行一个内嵌的 Alertmanager webhook 接收器。启用后，接收器在配置的路径上监听：
+
+```yaml
+alertmanager:
+ enabled: true
+ listen_path: "/api/v1/alerts"
+```
+
+| 键 | 类型 | 描述 |
+|-----|------|-------------|
+| `enabled` | `bool` | 当该部分存在时默认启用。 |
+| `listen_path` | `string` | 接收 Alertmanager webhook 的 HTTP 路径。默认为 `/api/v1/alerts`。必须以 `/` 开头且不含空白字符。 |
+
+将您的 Alertmanager 实例指向控制器的地址并使用此 webhook URL。告警会根据事件过滤器转发到已配置的通知渠道。
+
+## SMTP
+
+SMTP 通过邮件发送通知：
+
+| 键 | 类型 | 启用时必填 | 描述 |
+|-----|------|-----------------------|-------------|
+| `enabled` | `bool` | 否 | 当该部分存在时默认启用。 |
+| `host` | `string` | 是 | SMTP 服务器主机名。 |
+| `port` | `int` | 是 | SMTP 端口，1 到 65535。 |
+| `encryption` | `string` | 否 | `none`、`starttls` 或 `ssl_tls`。默认为 `starttls`。 |
+| `username` | `string` | 否 | SMTP 认证用户名。 |
+| `password` | `string` | 否 | SMTP 密码。 |
+| `password_file` | `string` | 否 | 从文件读取密码。 |
+| `from` | `string` | 是 | 发件人地址。 |
+| `to` | `[]string` | 是 | 收件人地址列表。 |
+| `on` | `[]string` | 否 | 要通知的事件类型。 |
+| `task_sources` | `[]string` | 否 | 任务来源过滤器。 |
+
+## Telegram
+
+Telegram 通过机器人向聊天发送通知：
+
+| 键 | 类型 | 启用时必填 | 描述 |
+|-----|------|-----------------------|-------------|
+| `enabled` | `bool` | 否 | 当该部分存在时默认启用。 |
+| `bot_token` | `string` | 是 | 从 BotFather 获取的 Telegram 机器人令牌。 |
+| `bot_token_file` | `string` | 否 | 从文件读取机器人令牌。 |
+| `chat_id` | `string` | 是 | 目标聊天 ID。 |
+| `on` | `[]string` | 否 | 要通知的事件类型。 |
+| `task_sources` | `[]string` | 否 | 任务来源过滤器。 |
diff --git a/site/content/docs/guide/notifications.zh-hant.md b/site/content/docs/guide/notifications.zh-hant.md
new file mode 100644
index 0000000..28adf7b
--- /dev/null
+++ b/site/content/docs/guide/notifications.zh-hant.md
@@ -0,0 +1,124 @@
+---
+title: "通知"
+date: '2026-05-26T00:00:00+08:00'
+weight: 70
+---
+
+Composia 為任務結果、備份事件、映像檔更新和節點狀態變更發送通知。支援三種通知管道：Alertmanager、SMTP 與 Telegram。
+
+## 設定
+
+所有管道都在控制器設定的 `notifications` 下設定：
+
+```yaml
+controller:
+ notifications:
+ alertmanager:
+ enabled: true
+ listen_path: "/api/v1/alerts"
+ smtp:
+ enabled: true
+ host: "smtp.example.com"
+ port: 587
+ encryption: starttls
+ username: "alerts@example.com"
+ password: "REPLACE"
+ from: "alerts@example.com"
+ to:
+ - "admin@example.com"
+ on:
+ - task_failed
+ - backup_failed
+ task_sources:
+ - web
+ - cli
+ telegram:
+ enabled: true
+ bot_token: "REPLACE"
+ chat_id: "REPLACE"
+ on:
+ - task_completed
+```
+
+## 事件型別
+
+提供以下通知事件型別：
+
+| 事件 | 觸發條件 |
+|-------|---------|
+| `task_failed` | 任何任務以 `failed` 狀態結束。 |
+| `task_cancelled` | 任務在完成前被取消。 |
+| `task_completed` | 任務成功完成。 |
+| `task_awaiting_confirmation` | 遷移任務到達確認步驟。 |
+| `backup_completed` | 備份任務或排程備份成功完成。 |
+| `backup_failed` | 備份任務或步驟失敗。 |
+| `image_update_available` | 映像檔檢查發現新版本。 |
+| `image_update_applied` | 映像檔更新已套用。 |
+| `node_offline` | 節點停止發送心跳。 |
+| `node_online` | 先前離線的節點恢復心跳。 |
+| `alertmanager_alert` | 當控制器設定為 Alertmanager webhook 接收器時收到 Alertmanager 警報。 |
+
+每個管道可以使用 `on` 清單過濾應處理的事件型別。空的 `on` 清單會發送所有事件型別。
+
+## 任務來源過濾器
+
+SMTP 和 Telegram 管道支援按觸發任務的來源進行過濾：
+
+| 來源 | 說明 |
+|--------|-------------|
+| `web` | 透過 Web UI 觸發的操作。 |
+| `cli` | 透過 CLI 觸發的操作。 |
+| `others` | 其他來源。 |
+| `schedule` | 排程任務（備份、維護）。 |
+| `system` | 系統產生的任務。 |
+| `auto_deploy` | 自動部署觸發器產生的任務。 |
+
+當 `task_sources` 為空白時，所有來源型別都會發送通知。
+
+## Alertmanager
+
+控制器執行一個內嵌的 Alertmanager webhook 接收器。啟用後，接收器在設定的路徑上監聽：
+
+```yaml
+alertmanager:
+ enabled: true
+ listen_path: "/api/v1/alerts"
+```
+
+| 鍵 | 型別 | 說明 |
+|-----|------|-------------|
+| `enabled` | `bool` | 當區段存在時預設啟用。 |
+| `listen_path` | `string` | 接收 Alertmanager webhook 的 HTTP 路徑。預設為 `/api/v1/alerts`。必須以 `/` 開頭且不含空白字元。 |
+
+將您的 Alertmanager 執行實例指向控制器的位址及此 webhook URL。警報會根據其事件過濾器轉發到已設定的通知管道。
+
+## SMTP
+
+SMTP 透過電子郵件發送通知：
+
+| 鍵 | 型別 | 啟用時必要 | 說明 |
+|-----|------|-----------------------|-------------|
+| `enabled` | `bool` | 否 | 當區段存在時預設啟用。 |
+| `host` | `string` | 是 | SMTP 伺服器主機名稱。 |
+| `port` | `int` | 是 | SMTP 連接埠，必須在 1 到 65535 之間。 |
+| `encryption` | `string` | 否 | `none`、`starttls` 或 `ssl_tls`。預設為 `starttls`。 |
+| `username` | `string` | 否 | SMTP 驗證使用者名稱。 |
+| `password` | `string` | 否 | SMTP 密碼。 |
+| `password_file` | `string` | 否 | 從檔案讀取密碼。 |
+| `from` | `string` | 是 | 寄件者地址。 |
+| `to` | `[]string` | 是 | 收件者地址。 |
+| `on` | `[]string` | 否 | 要通知的事件型別。 |
+| `task_sources` | `[]string` | 否 | 任務來源過濾器。 |
+
+## Telegram
+
+Telegram 透過機器人向聊天室發送通知：
+
+| 鍵 | 型別 | 啟用時必要 | 說明 |
+|-----|------|-----------------------|-------------|
+| `enabled` | `bool` | 否 | 當區段存在時預設啟用。 |
+| `bot_token` | `string` | 是 | 來自 BotFather 的 Telegram 機器人權杖。 |
+| `bot_token_file` | `string` | 否 | 從檔案讀取機器人權杖。 |
+| `chat_id` | `string` | 是 | 目標聊天室 ID。 |
+| `on` | `[]string` | 否 | 要通知的事件型別。 |
+| `task_sources` | `[]string` | 否 | 任務來源過濾器。 |
diff --git a/site/content/docs/guide/reverse-proxy.de.md b/site/content/docs/guide/reverse-proxy.de.md
new file mode 100644
index 0000000..39f5128
--- /dev/null
+++ b/site/content/docs/guide/reverse-proxy.de.md
@@ -0,0 +1,123 @@
+---
+title: "Reverse-Proxy"
+date: '2026-05-26T00:00:00+08:00'
+weight: 30
+---
+
+Composia integriert sich mit Caddy für die Reverse-Proxy-Verwaltung. Der Caddy-Infrastrukturdienst läuft als normaler Docker-Compose-Dienst, und Composia synchronisiert Caddy-Konfigurationsdateien beim Deploy und Stopp.
+
+## Architektur
+
+```
+Controller-Repo
+ ├── caddy/
+ │ ├── docker-compose.yaml (Caddy-Compose-Dienst)
+ │ ├── Caddyfile (Haupt-Caddy-Konfiguration, importiert generierte Dateien)
+ │ └── composia-meta.yaml (deklariert infra.caddy)
+ ├── my-app/
+ │ ├── docker-compose.yaml
+ │ ├── Caddyfile (dienstspezifische Caddy-Konfiguration)
+ │ └── composia-meta.yaml (deklariert network.caddy)
+ └── ...
+```
+
+Beim Deploy kopiert Composia die Caddyfile jedes Dienstes in ein generiertes Verzeichnis und löst dann ein Caddy-Reload aus.
+
+## Infrastruktur-Einrichtung
+
+Deklariere genau einen Caddy-Infrastrukturdienst im Repo:
+
+```yaml {filename="caddy/composia-meta.yaml"}
+name: caddy
+nodes:
+ - main
+infra:
+ caddy:
+ compose_service: caddy
+ config_dir: /etc/caddy
+```
+
+Die Haupt-Caddyfile im Caddy-Dienstverzeichnis sollte die generierten Dateien importieren:
+
+```caddy {filename="caddy/Caddyfile"}
+import /etc/caddy/generated/*.caddy
+```
+
+| Schlüssel | Typ | Beschreibung |
+|-----|------|-------------|
+| `compose_service` | `string` | Name des Compose-Dienstes. Standardmäßig `caddy`. |
+| `config_dir` | `string` | Caddy-Konfigurationsverzeichnis im Container. Standardmäßig `/etc/caddy`. |
+
+Nur ein Dienst im Repository kann als Caddy-Infrastruktur deklariert werden.
+
+## Dienstkonfiguration
+
+Aktiviere Caddy in `composia-meta.yaml` für jeden Dienst, der einen Reverse-Proxy-Eintrag benötigt, und stelle eine Caddyfile bereit:
+
+```yaml {filename="my-app/composia-meta.yaml"}
+name: my-app
+nodes:
+ - main
+network:
+ caddy:
+ enabled: true
+ source: Caddyfile
+```
+
+Der `source`-Pfad ist relativ zum Dienstverzeichnis und muss darin bleiben. Die Datei kann beliebig benannt werden, aber `Caddyfile` ist die Konvention.
+
+```caddy {filename="my-app/Caddyfile"}
+app.example.com {
+ reverse_proxy app:8080
+}
+```
+
+## Wie die Synchronisation funktioniert
+
+Während einer Deploy- oder Update-Aufgabe führt der Agent einen Caddy-Sync-Schritt nach `compose up` aus:
+
+1. Liest `network.caddy.source` aus der `composia-meta.yaml` des Dienstes.
+2. Kopiert die Quelldatei nach `/caddy/generated/.caddy`.
+3. Führt `docker compose exec caddy reload --config --adapter caddyfile` aus.
+
+Der generierte Dateiname wird vom Dienstverzeichnisnamen abgeleitet. Für `my-app` lautet die Datei `my-app.caddy`.
+
+Während einer Stopp-Aufgabe wird die generierte Caddy-Datei entfernt.
+
+## Caddy-Sync-Aufgabe
+
+Eine eigenständige `caddy_sync`-Aufgabe erstellt die Caddy-Konfiguration neu, ohne Dienste zu deployen. Sie kann in zwei Modi arbeiten:
+
+**Vollständiger Neuaufbau** (`full_rebuild: true`): Löscht alle generierten `.caddy`-Dateien aus dem generierten Verzeichnis und synchronisiert dann alle Caddy-verwalteten Dienste neu.
+
+**Gezielte Synchronisation**: Synchronisiert nur die angegebenen Dienstverzeichnisse.
+
+Über die Web-UI oder CLI auslösen:
+
+```bash
+composia service caddy-sync my-app
+```
+
+## Caddy-Reload-Aufgabe
+
+Eine `caddy_reload`-Aufgabe führt `caddy reload` im Caddy-Container aus, ohne Dateien zu ändern. Verwende sie nach manueller Bearbeitung der Haupt-Caddyfile:
+
+```bash
+composia node reload-caddy main
+```
+
+## Agent-Konfiguration
+
+Die Agent-Konfiguration hat einen optionalen Caddy-Abschnitt:
+
+```yaml
+agent:
+ caddy:
+ generated_dir: "/data/state-agent/caddy/generated"
+```
+
+| Schlüssel | Typ | Beschreibung |
+|-----|------|-------------|
+| `generated_dir` | `string` | Generiertes Caddy-Konfigurationsverzeichnis. Standardmäßig `/caddy/generated`. |
+
+Das generierte Verzeichnis muss sich in einem Pfad befinden, den der Caddy-Container lesen kann. Der Caddy-Compose-Dienst muss ein Volume haben, das dieses Verzeichnis auf den Pfad einbindet, der in der Haupt-Caddyfile importiert wird.
diff --git a/site/content/docs/guide/reverse-proxy.fr.md b/site/content/docs/guide/reverse-proxy.fr.md
new file mode 100644
index 0000000..9abda1e
--- /dev/null
+++ b/site/content/docs/guide/reverse-proxy.fr.md
@@ -0,0 +1,123 @@
+---
+title: "Reverse proxy"
+date: '2026-05-26T00:00:00+08:00'
+weight: 30
+---
+
+Composia s'intègre avec Caddy pour la gestion du reverse proxy. Le service d'infrastructure Caddy s'exécute comme un service Docker Compose normal, et Composia synchronise les fichiers de configuration Caddy au déploiement et à l'arrêt.
+
+## Architecture
+
+```
+Controller repo
+ ├── caddy/
+ │ ├── docker-compose.yaml (service Compose Caddy)
+ │ ├── Caddyfile (configuration Caddy principale, importe les fichiers générés)
+ │ └── composia-meta.yaml (déclare infra.caddy)
+ ├── my-app/
+ │ ├── docker-compose.yaml
+ │ ├── Caddyfile (configuration Caddy spécifique au service)
+ │ └── composia-meta.yaml (déclare network.caddy)
+ └── ...
+```
+
+Au moment du déploiement, Composia copie le Caddyfile de chaque service dans un répertoire généré, puis déclenche un rechargement Caddy.
+
+## Configuration de l'infrastructure
+
+Déclarez exactement un service d'infrastructure Caddy dans le dépôt :
+
+```yaml {filename="caddy/composia-meta.yaml"}
+name: caddy
+nodes:
+ - main
+infra:
+ caddy:
+ compose_service: caddy
+ config_dir: /etc/caddy
+```
+
+Le Caddyfile principal dans le répertoire du service Caddy doit importer les fichiers générés :
+
+```caddy {filename="caddy/Caddyfile"}
+import /etc/caddy/generated/*.caddy
+```
+
+| Clé | Type | Description |
+|-----|------|-------------|
+| `compose_service` | `string` | Nom du service Compose. Par défaut `caddy`. |
+| `config_dir` | `string` | Répertoire de configuration Caddy à l'intérieur du conteneur. Par défaut `/etc/caddy`. |
+
+Un seul service dans le dépôt peut être déclaré comme infrastructure Caddy.
+
+## Configuration du service
+
+Pour chaque service qui nécessite une entrée de reverse proxy, activez Caddy dans `composia-meta.yaml` et fournissez un Caddyfile :
+
+```yaml {filename="my-app/composia-meta.yaml"}
+name: my-app
+nodes:
+ - main
+network:
+ caddy:
+ enabled: true
+ source: Caddyfile
+```
+
+Le chemin `source` est relatif au répertoire du service et doit rester à l'intérieur. Le fichier peut avoir n'importe quel nom, mais `Caddyfile` est la convention.
+
+```caddy {filename="my-app/Caddyfile"}
+app.example.com {
+ reverse_proxy app:8080
+}
+```
+
+## Fonctionnement de la synchronisation
+
+Pendant une tâche de déploiement ou de mise à jour, l'agent exécute une étape de synchronisation Caddy après `compose up` :
+
+1. Lire `network.caddy.source` depuis le fichier `composia-meta.yaml` du service.
+2. Copier le fichier source vers `/caddy/generated/.caddy`.
+3. Exécuter `docker compose exec caddy reload --config --adapter caddyfile`.
+
+Le nom du fichier généré est dérivé du nom du répertoire du service. Pour `my-app`, le fichier est `my-app.caddy`.
+
+Pendant une tâche d'arrêt, le fichier Caddy généré est supprimé.
+
+## Tâche de synchronisation Caddy
+
+Une tâche autonome `caddy_sync` reconstruit la configuration Caddy sans déployer de services. Elle peut fonctionner en deux modes :
+
+**Reconstruction complète** (`full_rebuild: true`) : supprime tous les fichiers `.caddy` générés du répertoire généré, puis resynchronise tous les services gérés par Caddy.
+
+**Synchronisation ciblée** : synchronise uniquement les répertoires de service spécifiés.
+
+Déclenchez via l'interface web ou la CLI :
+
+```bash
+composia service caddy-sync my-app
+```
+
+## Tâche de rechargement Caddy
+
+Une tâche `caddy_reload` exécute `caddy reload` à l'intérieur du conteneur Caddy sans modifier aucun fichier. Utilisez-la après avoir modifié manuellement le Caddyfile principal :
+
+```bash
+composia node reload-caddy main
+```
+
+## Configuration de l'agent
+
+La configuration de l'agent a une section Caddy optionnelle :
+
+```yaml
+agent:
+ caddy:
+ generated_dir: "/data/state-agent/caddy/generated"
+```
+
+| Clé | Type | Description |
+|-----|------|-------------|
+| `generated_dir` | `string` | Répertoire de configuration Caddy généré. Par défaut `/caddy/generated`. |
+
+Le répertoire généré doit être à l'intérieur d'un chemin que le conteneur Caddy peut lire. Le service Compose Caddy doit avoir un volume montant ce répertoire vers le chemin importé dans le Caddyfile principal.
diff --git a/site/content/docs/guide/reverse-proxy.ja.md b/site/content/docs/guide/reverse-proxy.ja.md
new file mode 100644
index 0000000..9d4a97e
--- /dev/null
+++ b/site/content/docs/guide/reverse-proxy.ja.md
@@ -0,0 +1,123 @@
+---
+title: "リバースプロキシ"
+date: '2026-05-26T00:00:00+08:00'
+weight: 30
+---
+
+Composia はリバースプロキシ管理のために Caddy と統合します。Caddy インフラストラクチャサービスは通常の Docker Compose サービスとして実行され、Composia はデプロイ時と停止時に Caddy 設定ファイルを同期します。
+
+## アーキテクチャ
+
+```
+Controller repo
+ ├── caddy/
+ │ ├── docker-compose.yaml (Caddy Compose サービス)
+ │ ├── Caddyfile (メイン Caddy 設定、生成ファイルをインポート)
+ │ └── composia-meta.yaml (infra.caddy を宣言)
+ ├── my-app/
+ │ ├── docker-compose.yaml
+ │ ├── Caddyfile (サービス固有の Caddy 設定)
+ │ └── composia-meta.yaml (network.caddy を宣言)
+ └── ...
+```
+
+デプロイ時に、Composia は各サービスの Caddyfile を生成ディレクトリにコピーし、Caddy のリロードをトリガーします。
+
+## インフラストラクチャのセットアップ
+
+リポジトリに Caddy インフラストラクチャサービスを 1 つだけ宣言します:
+
+```yaml {filename="caddy/composia-meta.yaml"}
+name: caddy
+nodes:
+ - main
+infra:
+ caddy:
+ compose_service: caddy
+ config_dir: /etc/caddy
+```
+
+Caddy サービスディレクトリのメイン Caddyfile は生成されたファイルをインポートする必要があります:
+
+```caddy {filename="caddy/Caddyfile"}
+import /etc/caddy/generated/*.caddy
+```
+
+| キー | 型 | 説明 |
+|-----|------|-------------|
+| `compose_service` | `string` | Compose サービス名。デフォルトは `caddy`。 |
+| `config_dir` | `string` | コンテナ内の Caddy 設定ディレクトリ。デフォルトは `/etc/caddy`。 |
+
+リポジトリ内で Caddy インフラストラクチャとして宣言できるサービスは 1 つだけです。
+
+## サービス設定
+
+リバースプロキシエントリが必要な各サービスについて、`composia-meta.yaml` で Caddy を有効にし、Caddyfile を提供します:
+
+```yaml {filename="my-app/composia-meta.yaml"}
+name: my-app
+nodes:
+ - main
+network:
+ caddy:
+ enabled: true
+ source: Caddyfile
+```
+
+`source` パスはサービスディレクトリからの相対パスで、その中に留まる必要があります。ファイル名は任意ですが、`Caddyfile` が慣例です。
+
+```caddy {filename="my-app/Caddyfile"}
+app.example.com {
+ reverse_proxy app:8080
+}
+```
+
+## 同期の仕組み
+
+デプロイまたは更新タスク中、エージェントは `compose up` の後に Caddy 同期ステップを実行します:
+
+1. サービスの `composia-meta.yaml` から `network.caddy.source` を読み取ります。
+2. ソースファイルを `/caddy/generated/.caddy` にコピーします。
+3. `docker compose exec caddy reload --config --adapter caddyfile` を実行します。
+
+生成されるファイル名はサービスディレクトリ名から派生します。`my-app` の場合、ファイルは `my-app.caddy` になります。
+
+停止タスク中は、生成された Caddy ファイルが削除されます。
+
+## Caddy 同期タスク
+
+スタンドアロンの `caddy_sync` タスクはサービスをデプロイせずに Caddy 設定を再構築します。2 つのモードで動作します:
+
+**完全再構築**（`full_rebuild: true`）: 生成ディレクトリからすべての `.caddy` ファイルを削除し、すべての Caddy 管理サービスを再同期します。
+
+**ターゲット同期**: 指定されたサービスディレクトリのみを同期します。
+
+Web UI または CLI からトリガーします:
+
+```bash
+composia service caddy-sync my-app
+```
+
+## Caddy リロードタスク
+
+`caddy_reload` タスクはファイルを変更せずに Caddy コンテナ内で `caddy reload` を実行します。メイン Caddyfile を手動で編集した後に使用します:
+
+```bash
+composia node reload-caddy main
+```
+
+## エージェント設定
+
+エージェント設定にはオプションの Caddy セクションがあります:
+
+```yaml
+agent:
+ caddy:
+ generated_dir: "/data/state-agent/caddy/generated"
+```
+
+| キー | 型 | 説明 |
+|-----|------|-------------|
+| `generated_dir` | `string` | 生成された Caddy 設定ディレクトリ。デフォルトは `/caddy/generated`。 |
+
+生成ディレクトリは Caddy コンテナが読み取れるパス内にある必要があります。Caddy compose サービスは、このディレクトリをメイン Caddyfile でインポートされるパスにマウントするボリュームを持つ必要があります。
diff --git a/site/content/docs/guide/reverse-proxy.zh-hans.md b/site/content/docs/guide/reverse-proxy.zh-hans.md
new file mode 100644
index 0000000..9a2daf4
--- /dev/null
+++ b/site/content/docs/guide/reverse-proxy.zh-hans.md
@@ -0,0 +1,123 @@
+---
+title: "反向代理"
+date: '2026-05-26T00:00:00+08:00'
+weight: 30
+---
+
+Composia 与 Caddy 集成以实现反向代理管理。Caddy 基础设施服务作为普通的 Docker Compose 服务运行，Composia 在部署和停止时同步 Caddy 配置文件。
+
+## 架构
+
+```
+Controller repo
+ ├── caddy/
+ │ ├── docker-compose.yaml （Caddy Compose 服务）
+ │ ├── Caddyfile （主 Caddy 配置，导入生成的文件）
+ │ └── composia-meta.yaml （声明 infra.caddy）
+ ├── my-app/
+ │ ├── docker-compose.yaml
+ │ ├── Caddyfile （服务专属的 Caddy 配置）
+ │ └── composia-meta.yaml （声明 network.caddy）
+ └── ...
+```
+
+在部署时，Composia 将每个服务的 Caddyfile 复制到生成的目录中，然后触发 Caddy 重载。
+
+## 基础设施设置
+
+在仓库中声明恰好一个 Caddy 基础设施服务：
+
+```yaml {filename="caddy/composia-meta.yaml"}
+name: caddy
+nodes:
+ - main
+infra:
+ caddy:
+ compose_service: caddy
+ config_dir: /etc/caddy
+```
+
+Caddy 服务目录中的主 Caddyfile 应导入生成的文件：
+
+```caddy {filename="caddy/Caddyfile"}
+import /etc/caddy/generated/*.caddy
+```
+
+| 键 | 类型 | 描述 |
+|-----|------|-------------|
+| `compose_service` | `string` | Compose 服务名称。默认为 `caddy`。 |
+| `config_dir` | `string` | 容器内的 Caddy 配置目录。默认为 `/etc/caddy`。 |
+
+仓库中只能有一个服务被声明为 Caddy 基础设施。
+
+## 服务配置
+
+对于需要反向代理条目的每个服务，在 `composia-meta.yaml` 中启用 Caddy 并提供 Caddyfile：
+
+```yaml {filename="my-app/composia-meta.yaml"}
+name: my-app
+nodes:
+ - main
+network:
+ caddy:
+ enabled: true
+ source: Caddyfile
+```
+
+`source` 路径相对于服务目录，且必须保持在目录内。文件可以任意命名，但惯例是 `Caddyfile`。
+
+```caddy {filename="my-app/Caddyfile"}
+app.example.com {
+ reverse_proxy app:8080
+}
+```
+
+## 同步工作原理
+
+在部署或更新任务期间，agent 在 `compose up` 后运行 Caddy 同步步骤：
+
+1. 从服务的 `composia-meta.yaml` 读取 `network.caddy.source`。
+2. 将源文件复制到 `/caddy/generated/.caddy`。
+3. 运行 `docker compose exec caddy reload --config --adapter caddyfile`。
+
+生成的文件名从服务目录名派生。对于 `my-app`，文件名为 `my-app.caddy`。
+
+在停止任务期间，生成的 Caddy 文件会被删除。
+
+## Caddy 同步任务
+
+独立的 `caddy_sync` 任务在不部署服务的情况下重建 Caddy 配置。它支持两种模式：
+
+**完全重建** (`full_rebuild: true`): 删除生成目录中所有 `.caddy` 文件，然后重新同步所有受 Caddy 管理的服务。
+
+**定向同步**: 仅同步指定的服务目录。
+
+通过 Web UI 或 CLI 触发：
+
+```bash
+composia service caddy-sync my-app
+```
+
+## Caddy 重载任务
+
+`caddy_reload` 任务在 Caddy 容器内运行 `caddy reload`，而不更改任何文件。在手动编辑主 Caddyfile 后使用：
+
+```bash
+composia node reload-caddy main
+```
+
+## Agent 配置
+
+Agent 配置有一个可选的 Caddy 部分：
+
+```yaml
+agent:
+ caddy:
+ generated_dir: "/data/state-agent/caddy/generated"
+```
+
+| 键 | 类型 | 描述 |
+|-----|------|-------------|
+| `generated_dir` | `string` | 生成的 Caddy 配置目录。默认为 `/caddy/generated`。 |
+
+生成的目录必须位于 Caddy 容器可读取的路径内。Caddy compose 服务必须有一个卷将此目录挂载到主 Caddyfile 中导入的路径。
diff --git a/site/content/docs/guide/reverse-proxy.zh-hant.md b/site/content/docs/guide/reverse-proxy.zh-hant.md
new file mode 100644
index 0000000..4b34d0f
--- /dev/null
+++ b/site/content/docs/guide/reverse-proxy.zh-hant.md
@@ -0,0 +1,123 @@
+---
+title: "反向代理"
+date: '2026-05-26T00:00:00+08:00'
+weight: 30
+---
+
+Composia 與 Caddy 整合以管理反向代理。Caddy 基礎架構服務作為普通的 Docker Compose 服務執行，Composia 在部署和停止時同步 Caddy 設定檔。
+
+## 架構
+
+```
+Controller repo
+ ├── caddy/
+ │ ├── docker-compose.yaml (Caddy Compose 服務)
+ │ ├── Caddyfile (主要 Caddy 設定，匯入產生的檔案)
+ │ └── composia-meta.yaml (宣告 infra.caddy)
+ ├── my-app/
+ │ ├── docker-compose.yaml
+ │ ├── Caddyfile (服務專用的 Caddy 設定)
+ │ └── composia-meta.yaml (宣告 network.caddy)
+ └── ...
+```
+
+在部署時，Composia 將每個服務的 Caddyfile 複製到產生的目錄中，然後觸發 Caddy 重新載入。
+
+## 基礎架構設定
+
+在存放庫中宣告恰好一個 Caddy 基礎架構服務：
+
+```yaml {filename="caddy/composia-meta.yaml"}
+name: caddy
+nodes:
+ - main
+infra:
+ caddy:
+ compose_service: caddy
+ config_dir: /etc/caddy
+```
+
+Caddy 服務目錄中的主要 Caddyfile 應匯入產生的檔案：
+
+```caddy {filename="caddy/Caddyfile"}
+import /etc/caddy/generated/*.caddy
+```
+
+| 鍵 | 型別 | 說明 |
+|-----|------|-------------|
+| `compose_service` | `string` | Compose 服務名稱。預設為 `caddy`。 |
+| `config_dir` | `string` | 容器內的 Caddy 設定目錄。預設為 `/etc/caddy`。 |
+
+存放庫中只有一個服務可以宣告為 Caddy 基礎架構。
+
+## 服務設定
+
+對於需要反向代理項目的每個服務，在 `composia-meta.yaml` 中啟用 Caddy 並提供一個 Caddyfile：
+
+```yaml {filename="my-app/composia-meta.yaml"}
+name: my-app
+nodes:
+ - main
+network:
+ caddy:
+ enabled: true
+ source: Caddyfile
+```
+
+`source` 路徑相對於服務目錄，且必須保持在該目錄內。檔案可以任意命名，但慣例上使用 `Caddyfile`。
+
+```caddy {filename="my-app/Caddyfile"}
+app.example.com {
+ reverse_proxy app:8080
+}
+```
+
+## 同步運作方式
+
+在部署或更新任務期間，代理在 `compose up` 之後執行 Caddy 同步步驟：
+
+1. 從服務的 `composia-meta.yaml` 讀取 `network.caddy.source`。
+2. 將來源檔案複製到 `/caddy/generated/.caddy`。
+3. 執行 `docker compose exec caddy reload --config --adapter caddyfile`。
+
+產生的檔案名稱來自服務目錄名稱。對於 `my-app`，檔案為 `my-app.caddy`。
+
+在停止任務期間，產生的 Caddy 檔案會被移除。
+
+## Caddy 同步任務
+
+獨立的 `caddy_sync` 任務在不部署服務的情況下重建 Caddy 設定。它可以以兩種模式運作：
+
+**完全重建** (`full_rebuild: true`)：從產生的目錄中刪除所有產生的 `.caddy` 檔案，然後重新同步所有由 Caddy 管理的服務。
+
+**定向同步**：僅同步指定的服務目錄。
+
+透過 Web UI 或 CLI 觸發：
+
+```bash
+composia service caddy-sync my-app
+```
+
+## Caddy 重新載入任務
+
+`caddy_reload` 任務在 Caddy 容器內執行 `caddy reload`，不變更任何檔案。在手動編輯主要 Caddyfile 後使用：
+
+```bash
+composia node reload-caddy main
+```
+
+## 代理設定
+
+代理設定有一個可選的 Caddy 區段：
+
+```yaml
+agent:
+ caddy:
+ generated_dir: "/data/state-agent/caddy/generated"
+```
+
+| 鍵 | 型別 | 說明 |
+|-----|------|-------------|
+| `generated_dir` | `string` | 產生的 Caddy 設定目錄。預設為 `/caddy/generated`。 |
+
+產生的目錄必須位於 Caddy 容器可以讀取的路徑內。Caddy compose 服務必須有一個將此目錄掛載到主要 Caddyfile 中所匯入路徑的磁碟區。
diff --git a/site/content/docs/guide/secrets.de.md b/site/content/docs/guide/secrets.de.md
new file mode 100644
index 0000000..d6a5c82
--- /dev/null
+++ b/site/content/docs/guide/secrets.de.md
@@ -0,0 +1,98 @@
+---
+title: "Secrets"
+date: '2026-05-26T00:00:00+08:00'
+weight: 50
+---
+
+Composia verwaltet verschlüsselte Secret-Dateien im Sollzustand-Repository mit Age-Verschlüsselung. Ver- und Entschlüsselung finden auf dem Controller statt. Agenten erhalten niemals Zugriff auf den privaten Age-Schlüssel.
+
+## Konfiguration
+
+Secrets erfordern ein Age-Schlüsselpaar. In der Controller-Konfiguration einrichten:
+
+```yaml
+controller:
+ secrets:
+ provider: age
+ identity_file: "/app/configs/age-identity.key"
+```
+
+| Schlüssel | Typ | Erforderlich | Beschreibung |
+|-----|------|----------|-------------|
+| `provider` | `string` | Ja | Muss `age` sein. |
+| `identity_file` | `string` | Ja | Pfad zur privaten Age-Schlüsseldatei. |
+| `recipient_file` | `string` | Nein | Pfad zur Datei mit Age-Empfängern (öffentliche Schlüssel). Wenn weggelassen, wird der Empfänger vom privaten Schlüssel abgeleitet. |
+| `armor` | `bool` | Nein | Verwendet ASCII-armierte Ausgabe. Standardmäßig `true`. |
+
+Generiere ein Schlüsselpaar:
+
+```bash
+age-keygen -o age-identity.key
+```
+
+Optional: Extrahiere den öffentlichen Schlüssel als Empfänger:
+
+```bash
+age-keygen -y age-identity.key > age-recipients.txt
+```
+
+## Wie Secrets gespeichert werden
+
+Secret-Dateien im Repository haben konventionsgemäß die Erweiterung `.enc`. Sie werden als Age-verschlüsselter Geheimtext gespeichert:
+
+```
+my-app/
+├── docker-compose.yaml
+├── composia-meta.yaml
+└── .secret.env.enc (mit Age verschlüsselt)
+```
+
+Der Controller verschlüsselt Klartext beim Schreiben und entschlüsselt beim Lesen. Das Repository enthält nur Geheimtext. Secrets erscheinen niemals als Klartext im Repo, in Aufgabenprotokollen oder bei der Übertragung an Agenten.
+
+## Wie Secrets zu Agenten gelangen
+
+Während des Render-Schritts einer Deploy- oder Update-Aufgabe:
+
+1. Liest der Controller verschlüsselte Dateien aus dem Dienstverzeichnis im Repo.
+2. Entschlüsselt jede Datei mit dem privaten Age-Schlüssel.
+3. Injiziert den entschlüsselten Inhalt als `.composia-secret.env` in das Dienstpaket.
+
+Das Paket wird über die Agent-Report-Verbindung an den Agenten gestreamt. Der Agent schreibt das Paket auf die Festplatte und fährt mit `docker compose up` fort. Die entschlüsselte Secret-Umgebung steht den Compose-Diensten zur Verfügung, ohne dass der Agent jemals den privaten Schlüssel sieht.
+
+## CLI-Nutzung
+
+Schreibe eine verschlüsselte Secret-Datei:
+
+```bash
+composia secret update my-app .secret.env.enc --file ./local-plain.env
+```
+
+Lese und entschlüssele eine Secret-Datei:
+
+```bash
+composia secret get my-app .secret.env.enc
+```
+
+Bearbeite ein Secret direkt (öffnet deinen Editor):
+
+```bash
+composia secret edit my-app .secret.env.enc
+```
+
+Alle Secret-Schreiboperationen beinhalten eine Basis-Revisionsprüfung, um Konflikte mit gleichzeitigen Änderungen zu verhindern.
+
+## Dateipfad-Regeln
+
+Secret-Dateipfade müssen:
+
+- Relativ zum Dienstverzeichnis sein (nicht absolut).
+- Keine Pfadtraversierungssequenzen wie `../` enthalten.
+- Auf eine Datei innerhalb des Dienstverzeichnisses verweisen.
+
+Der Controller lokalisiert den Dienst, löst den Dateipfad relativ zum Dienstverzeichnis auf und operiert auf der Repo-Datei.
+
+## Fehlerbedingungen
+
+- **Secrets nicht konfiguriert**: `GetSecret` und `UpdateSecret` geben `FailedPrecondition` zurück, wenn `controller.secrets` nicht gesetzt ist.
+- **Datei nicht gefunden**: `GetSecret` gibt eine leere Inhaltsantwort statt eines Fehlers zurück, wenn die Datei nicht existiert. Dies ermöglicht Clients, zwischen fehlenden Dateien und Entschlüsselungsfehlern zu unterscheiden.
+- **Basis-Revisionskonflikt**: `UpdateSecret` verwendet CAS (Compare-and-Swap) gegen den Repo-HEAD. Wenn sich das Repo seit dem letzten Lesen geändert hat, schlägt das Schreiben mit einem Revisionskonflikt fehl.
diff --git a/site/content/docs/guide/secrets.fr.md b/site/content/docs/guide/secrets.fr.md
new file mode 100644
index 0000000..692ecfd
--- /dev/null
+++ b/site/content/docs/guide/secrets.fr.md
@@ -0,0 +1,98 @@
+---
+title: "Secrets"
+date: '2026-05-26T00:00:00+08:00'
+weight: 50
+---
+
+Composia gère les fichiers de secrets chiffrés dans le dépôt d'état désiré en utilisant le chiffrement age. Le chiffrement et le déchiffrement ont lieu sur le contrôleur. Les agents n'accèdent jamais à la clé privée age.
+
+## Configuration
+
+Les secrets nécessitent une paire de clés age. Configurez-la dans la configuration du contrôleur :
+
+```yaml
+controller:
+ secrets:
+ provider: age
+ identity_file: "/app/configs/age-identity.key"
+```
+
+| Clé | Type | Requis | Description |
+|-----|------|----------|-------------|
+| `provider` | `string` | Oui | Doit être `age`. |
+| `identity_file` | `string` | Oui | Chemin vers le fichier de clé privée age. |
+| `recipient_file` | `string` | Non | Chemin vers le fichier contenant les destinataires age (clés publiques). Si omis, le destinataire est dérivé de la clé privée. |
+| `armor` | `bool` | Non | Utiliser une sortie en armure ASCII. Par défaut `true`. |
+
+Générez une paire de clés :
+
+```bash
+age-keygen -o age-identity.key
+```
+
+Optionnel : extrayez la clé publique comme destinataire :
+
+```bash
+age-keygen -y age-identity.key > age-recipients.txt
+```
+
+## Comment les secrets sont stockés
+
+Les fichiers de secrets dans le dépôt ont une extension `.enc` par convention. Ils sont stockés sous forme de texte chiffré age :
+
+```
+my-app/
+├── docker-compose.yaml
+├── composia-meta.yaml
+└── .secret.env.enc (chiffré avec age)
+```
+
+Le contrôleur chiffre le texte en clair à l'écriture et déchiffre à la lecture. Le dépôt contient uniquement du texte chiffré. Les secrets n'apparaissent jamais en clair dans le dépôt, dans les journaux de tâches ou en transit vers les agents.
+
+## Comment les secrets parviennent aux agents
+
+Pendant l'étape de rendu d'une tâche de déploiement ou de mise à jour, le contrôleur :
+
+1. Lit les fichiers chiffrés depuis le répertoire du service dans le dépôt.
+2. Déchiffre chaque fichier en utilisant la clé privée age.
+3. Injecte le contenu déchiffré dans le bundle de service sous forme de `.composia-secret.env`.
+
+Le bundle est transmis à l'agent via la connexion de rapport de l'agent. L'agent écrit le bundle sur disque et procède à `docker compose up`. L'environnement de secret déchiffré est disponible pour les services Compose sans que l'agent ne voie jamais la clé privée.
+
+## Utilisation de la CLI
+
+Écrire un fichier de secret chiffré :
+
+```bash
+composia secret update my-app .secret.env.enc --file ./local-plain.env
+```
+
+Lire et déchiffrer un fichier de secret :
+
+```bash
+composia secret get my-app .secret.env.enc
+```
+
+Modifier un secret sur place (ouvre votre éditeur) :
+
+```bash
+composia secret edit my-app .secret.env.enc
+```
+
+Toutes les opérations d'écriture de secrets incluent une vérification de révision de base pour éviter les conflits avec des modifications concurrentes.
+
+## Règles de chemin de fichier
+
+Les chemins de fichiers de secrets doivent :
+
+- Être relatifs au répertoire du service (pas absolus).
+- Ne pas contenir de séquences de traversée de chemin comme `../`.
+- Pointer vers un fichier à l'intérieur du répertoire du service.
+
+Le contrôleur localise le service, résout le chemin du fichier relativement au répertoire du service et opère sur le fichier du dépôt.
+
+## Conditions d'erreur
+
+- **Secrets non configurés** : `GetSecret` et `UpdateSecret` retournent `FailedPrecondition` lorsque `controller.secrets` n'est pas défini.
+- **Fichier introuvable** : `GetSecret` retourne une réponse avec un contenu vide plutôt qu'une erreur lorsque le fichier n'existe pas. Cela permet aux clients de distinguer les fichiers manquants des échecs de déchiffrement.
+- **Conflit de révision de base** : `UpdateSecret` utilise CAS (compare-and-swap) par rapport à HEAD du dépôt. Si le dépôt a changé depuis la dernière lecture, l'écriture échoue avec un conflit de révision.
diff --git a/site/content/docs/guide/secrets.ja.md b/site/content/docs/guide/secrets.ja.md
new file mode 100644
index 0000000..4d5dc69
--- /dev/null
+++ b/site/content/docs/guide/secrets.ja.md
@@ -0,0 +1,98 @@
+---
+title: "シークレット"
+date: '2026-05-26T00:00:00+08:00'
+weight: 50
+---
+
+Composia は age 暗号化を使用して期待状態リポジトリ内の暗号化シークレットファイルを管理します。暗号化と復号はコントローラー上で行われます。エージェントは age 秘密鍵に一切アクセスしません。
+
+## 設定
+
+シークレットには age 鍵ペアが必要です。コントローラー設定で設定します:
+
+```yaml
+controller:
+ secrets:
+ provider: age
+ identity_file: "/app/configs/age-identity.key"
+```
+
+| キー | 型 | 必須 | 説明 |
+|-----|------|----------|-------------|
+| `provider` | `string` | はい | `age` である必要があります。 |
+| `identity_file` | `string` | はい | age 秘密鍵ファイルへのパス。 |
+| `recipient_file` | `string` | いいえ | age 受信者（公開鍵）を含むファイルへのパス。省略した場合、受信者は秘密鍵から導出されます。 |
+| `armor` | `bool` | いいえ | ASCII アーマー出力を使用します。デフォルトは `true`。 |
+
+鍵ペアの生成:
+
+```bash
+age-keygen -o age-identity.key
+```
+
+オプション: 公開鍵を受信者として抽出:
+
+```bash
+age-keygen -y age-identity.key > age-recipients.txt
+```
+
+## シークレットの保存方法
+
+リポジトリ内のシークレットファイルは慣例として `.enc` 拡張子を持ちます。age 暗号化された暗号文として保存されます:
+
+```
+my-app/
+├── docker-compose.yaml
+├── composia-meta.yaml
+└── .secret.env.enc (age で暗号化)
+```
+
+コントローラーは書き込み時に平文を暗号化し、読み取り時に復号します。リポジトリには暗号文のみが含まれます。シークレットがリポジトリ内、タスクログ内、またはエージェントへの転送中に平文で現れることはありません。
+
+## シークレットがエージェントに届く仕組み
+
+デプロイまたは更新タスクのレンダリングステップ中に、コントローラーは:
+
+1. リポジトリ内のサービスディレクトリから暗号化ファイルを読み取ります。
+2. age 秘密鍵を使用して各ファイルを復号します。
+3. 復号されたコンテンツを `.composia-secret.env` としてサービスバンドルに注入します。
+
+バンドルはエージェントレポート接続を通じてエージェントにストリーミングされます。エージェントはバンドルをディスクに書き込み、`docker compose up` を続行します。復号されたシークレット環境は、エージェントが秘密鍵を見ることなく Compose サービスから利用可能になります。
+
+## CLI の使用
+
+暗号化シークレットファイルの書き込み:
+
+```bash
+composia secret update my-app .secret.env.enc --file ./local-plain.env
+```
+
+シークレットファイルの読み取りと復号:
+
+```bash
+composia secret get my-app .secret.env.enc
+```
+
+シークレットのインプレース編集（エディタが開きます）:
+
+```bash
+composia secret edit my-app .secret.env.enc
+```
+
+すべてのシークレット書き込み操作には、同時変更との競合を防ぐためのベースリビジョンチェックが含まれます。
+
+## ファイルパスのルール
+
+シークレットファイルのパスは:
+
+- サービスディレクトリからの相対パス（絶対パスではない）である必要があります。
+- `../` のようなパス横断シーケンスを含んではいけません。
+- サービスディレクトリ内のファイルを指す必要があります。
+
+コントローラーはサービスを見つけ、サービスディレクトリからの相対パスとしてファイルパスを解決し、リポジトリファイルに対して操作を行います。
+
+## エラー条件
+
+- **シークレット未設定**: `controller.secrets` が設定されていない場合、`GetSecret` と `UpdateSecret` は `FailedPrecondition` を返します。
+- **ファイルが見つからない**: `GetSecret` はファイルが存在しない場合、エラーではなく空のコンテンツレスポンスを返します。これによりクライアントはファイル不在と復号失敗を区別できます。
+- **ベースリビジョン競合**: `UpdateSecret` はリポジトリ HEAD に対して CAS（compare-and-swap）を使用します。最後の読み取り以降にリポジトリが変更された場合、書き込みはリビジョン競合で失敗します。
diff --git a/site/content/docs/guide/secrets.zh-hans.md b/site/content/docs/guide/secrets.zh-hans.md
new file mode 100644
index 0000000..120158f
--- /dev/null
+++ b/site/content/docs/guide/secrets.zh-hans.md
@@ -0,0 +1,98 @@
+---
+title: "密钥"
+date: '2026-05-26T00:00:00+08:00'
+weight: 50
+---
+
+Composia 使用 age 加密在期望状态仓库中管理加密的密钥文件。加密和解密在控制器上发生。Agent 永远不会访问 age 私钥。
+
+## 配置
+
+密钥需要一个 age 密钥对。在控制器配置中设置：
+
+```yaml
+controller:
+ secrets:
+ provider: age
+ identity_file: "/app/configs/age-identity.key"
+```
+
+| 键 | 类型 | 必填 | 描述 |
+|-----|------|----------|-------------|
+| `provider` | `string` | 是 | 必须为 `age`。 |
+| `identity_file` | `string` | 是 | age 私钥文件的路径。 |
+| `recipient_file` | `string` | 否 | 包含 age 接收者（公钥）的文件路径。如果省略，接收者从私钥派生。 |
+| `armor` | `bool` | 否 | 使用 ASCII 封装输出。默认为 `true`。 |
+
+生成密钥对：
+
+```bash
+age-keygen -o age-identity.key
+```
+
+可选：提取公钥作为接收者：
+
+```bash
+age-keygen -y age-identity.key > age-recipients.txt
+```
+
+## 密钥的存储方式
+
+仓库中的密钥文件按惯例带有 `.enc` 扩展名。它们以 age 加密的密文形式存储：
+
+```
+my-app/
+├── docker-compose.yaml
+├── composia-meta.yaml
+└── .secret.env.enc （使用 age 加密）
+```
+
+控制器在写入时加密明文，在读取时解密。仓库中只包含密文。密钥从不会以明文形式出现在仓库、任务日志或传输给 agent 的数据中。
+
+## 密钥如何到达 agent
+
+在部署或更新任务的渲染步骤中，控制器：
+
+1. 从仓库中的服务目录读取加密文件。
+2. 使用 age 私钥解密每个文件。
+3. 将解密后的内容作为 `.composia-secret.env` 注入服务包。
+
+服务包通过 agent 报告连接流式传输到 agent。Agent 将包写入磁盘并继续执行 `docker compose up`。解密后的密钥环境变量可供 Compose 服务使用，而 agent 永远不会看到私钥。
+
+## CLI 用法
+
+写入加密的密钥文件：
+
+```bash
+composia secret update my-app .secret.env.enc --file ./local-plain.env
+```
+
+读取并解密密钥文件：
+
+```bash
+composia secret get my-app .secret.env.enc
+```
+
+就地编辑密钥（打开编辑器）：
+
+```bash
+composia secret edit my-app .secret.env.enc
+```
+
+所有密钥写入操作都包含基准版本检查，以防止与并发更改冲突。
+
+## 文件路径规则
+
+密钥文件路径必须：
+
+- 相对于服务目录（不能是绝对路径）。
+- 不包含路径穿越序列，如 `../`。
+- 指向服务目录内的文件。
+
+控制器定位服务，相对于服务目录解析文件路径，并对仓库文件进行操作。
+
+## 错误情况
+
+- **密钥未配置**: 当 `controller.secrets` 未设置时，`GetSecret` 和 `UpdateSecret` 返回 `FailedPrecondition`。
+- **文件未找到**: 当文件不存在时，`GetSecret` 返回空内容响应而非错误。这使客户端能区分文件缺失和解密失败。
+- **基准版本冲突**: `UpdateSecret` 使用 CAS（比较并交换）机制针对仓库 HEAD。如果自上次读取以来仓库发生了变化，写入将因版本冲突而失败。
diff --git a/site/content/docs/guide/secrets.zh-hant.md b/site/content/docs/guide/secrets.zh-hant.md
new file mode 100644
index 0000000..53e606a
--- /dev/null
+++ b/site/content/docs/guide/secrets.zh-hant.md
@@ -0,0 +1,98 @@
+---
+title: "密鑰"
+date: '2026-05-26T00:00:00+08:00'
+weight: 50
+---
+
+Composia 使用 age 加密管理期望狀態存放庫中的加密密鑰檔案。加密和解密在控制器端進行。代理從不接觸 age 私鑰。
+
+## 設定
+
+密鑰需要一組 age 金鑰對。在控制器設定中設定：
+
+```yaml
+controller:
+ secrets:
+ provider: age
+ identity_file: "/app/configs/age-identity.key"
+```
+
+| 鍵 | 型別 | 必要 | 說明 |
+|-----|------|----------|-------------|
+| `provider` | `string` | 是 | 必須為 `age`。 |
+| `identity_file` | `string` | 是 | age 私鑰檔案的路徑。 |
+| `recipient_file` | `string` | 否 | 包含 age 接收者（公鑰）的檔案路徑。若省略，接收者從私鑰衍生。 |
+| `armor` | `bool` | 否 | 使用 ASCII armoring 輸出。預設為 `true`。 |
+
+產生金鑰對：
+
+```bash
+age-keygen -o age-identity.key
+```
+
+可選：提取公鑰作為接收者：
+
+```bash
+age-keygen -y age-identity.key > age-recipients.txt
+```
+
+## 密鑰的儲存方式
+
+存放庫中的密鑰檔案慣例上具有 `.enc` 副檔名。它們以 age 加密的密文形式儲存：
+
+```
+my-app/
+├── docker-compose.yaml
+├── composia-meta.yaml
+└── .secret.env.enc (以 age 加密)
+```
+
+控制器在寫入時加密明文，在讀取時解密。存放庫中僅包含密文。密鑰永遠不會以明文形式出現在存放庫、任務日誌或傳輸給代理的過程中。
+
+## 密鑰如何送達代理
+
+在部署或更新任務的渲染步驟中，控制器：
+
+1. 從存放庫中的服務目錄讀取加密檔案。
+2. 使用 age 私鑰解密每個檔案。
+3. 將解密後的內容作為 `.composia-secret.env` 注入服務包。
+
+服務包透過代理回報連線以串流方式傳送給代理。代理將服務包寫入磁碟，然後執行 `docker compose up`。解密的密鑰環境可供 Compose 服務使用，而代理從未見過私鑰。
+
+## CLI 使用
+
+寫入加密密鑰檔案：
+
+```bash
+composia secret update my-app .secret.env.enc --file ./local-plain.env
+```
+
+讀取並解密一個密鑰檔案：
+
+```bash
+composia secret get my-app .secret.env.enc
+```
+
+原地編輯密鑰（開啟您的編輯器）：
+
+```bash
+composia secret edit my-app .secret.env.enc
+```
+
+所有密鑰寫入操作都包含基礎修訂版本檢查，以防止與並行變更發生衝突。
+
+## 檔案路徑規則
+
+密鑰檔案路徑必須：
+
+- 相對於服務目錄（不能是絕對路徑）。
+- 不包含路徑遍歷序列，如 `../`。
+- 指向服務目錄內的檔案。
+
+控制器定位服務，相對於服務目錄解析檔案路徑，並對存放庫檔案進行操作。
+
+## 錯誤狀況
+
+- **密鑰未設定**：當 `controller.secrets` 未設定時，`GetSecret` 和 `UpdateSecret` 返回 `FailedPrecondition`。
+- **檔案不存在**：當檔案不存在時，`GetSecret` 返回空的內容回應而非錯誤。這讓客戶端能夠區分遺失檔案和解密失敗。
+- **基礎修訂版本衝突**：`UpdateSecret` 對存放庫 HEAD 使用 CAS（比較並交換）機制。如果存放庫自上次讀取後已變更，寫入會因修訂版本衝突而失敗。
diff --git a/site/content/docs/guide/service.de.md b/site/content/docs/guide/service.de.md
new file mode 100644
index 0000000..63e1006
--- /dev/null
+++ b/site/content/docs/guide/service.de.md
@@ -0,0 +1,308 @@
+---
+title: "Dienstkonfiguration"
+date: '2026-05-26T00:00:00+08:00'
+weight: 10
+---
+
+Jeder Dienst befindet sich in einem Verzeichnis innerhalb des Controller-Repositories. Ein Dienstverzeichnis enthält `composia-meta.yaml` und eine oder mehrere Docker-Compose-Dateien.
+
+Minimaler Dienst:
+
+```yaml {filename="composia-meta.yaml"}
+name: my-app
+nodes:
+ - main
+```
+
+Mit dem Standardverhalten sucht Composia nach `docker-compose.yaml` im selben Verzeichnis.
+
+## Schlüssel der obersten Ebene
+
+| Schlüssel | Typ | Erforderlich | Beschreibung |
+|-----|------|----------|-------------|
+| `name` | `string` | Ja | Eindeutiger Dienstname. |
+| `project_name` | `string` | Nein | Docker-Compose-Projektname-Override. Standardmäßig ein normalisierter Dienstname. |
+| `compose_files` | `[]string` | Nein | Compose-Dateipfade relativ zum Dienstverzeichnis. |
+| `enabled` | `bool` | Nein | Ob der Dienst aktiv ist. Standardmäßig `true`. |
+| `nodes` | `[]string` | Ja | Ziel-Node-IDs. Jede muss in `controller.nodes` existieren. |
+| `infra` | `object` | Nein | Deklariert diesen Dienst als Caddy-, Rustic- oder Config-Only-Infrastruktur. |
+| `network` | `object` | Nein | Caddy- und DNS-Einstellungen. |
+| `update` | `object` | Nein | Image-Update-Einstellungen. |
+| `data_protect` | `object` | Nein | Backup- und Restore-Datendefinitionen. |
+| `backup` | `object` | Nein | Geplante Backups für geschützte Daten. |
+| `migrate` | `object` | Nein | Migrationsfähige geschützte Daten. |
+| `auto_deploy` | `bool` | Nein | Diesen Dienst nach Repository-Änderungen automatisch deployen. |
+
+`compose_files`-Einträge müssen relative Pfade sein, innerhalb des Dienstverzeichnisses bleiben und dürfen nicht dupliziert sein.
+
+## Infrastrukturdienste
+
+### `infra.caddy`
+
+Deklariert den Caddy-Infrastrukturdienst des Repositories.
+
+```yaml
+infra:
+ caddy:
+ compose_service: caddy
+ config_dir: /etc/caddy
+```
+
+| Schlüssel | Typ | Beschreibung |
+|-----|------|-------------|
+| `compose_service` | `string` | Name des Compose-Dienstes. Standardmäßig `caddy`. |
+| `config_dir` | `string` | Caddy-Konfigurationsverzeichnis. Standardmäßig `/etc/caddy`. |
+
+Nur ein Dienst kann als Caddy-Infrastruktur deklariert werden.
+
+### `infra.rustic`
+
+Deklariert den Rustic-Infrastrukturdienst des Repositories.
+
+```yaml
+infra:
+ rustic:
+ compose_service: rustic
+ profile: default
+ data_protect_dir: /data-protect
+ init_args:
+ - --set-version
+ - "2"
+```
+
+| Schlüssel | Typ | Beschreibung |
+|-----|------|-------------|
+| `compose_service` | `string` | Name des Compose-Dienstes. Standardmäßig `rustic`. |
+| `profile` | `string` | Rustic-Profilname. |
+| `data_protect_dir` | `string` | Verzeichnis, das von Datenschutz-Workflows verwendet wird. |
+| `init_args` | `[]string` | Zusätzliche Argumente, die an `rustic init` übergeben werden. Leere Einträge werden abgelehnt. |
+
+Nur ein Dienst kann als Rustic-Infrastruktur deklariert werden.
+
+### `infra.config`
+
+Deklariert einen reinen Konfigurations-Infrastrukturdienst.
+
+```yaml
+infra:
+ config: {}
+```
+
+Config-Only-Dienste können nicht mit `infra.caddy` oder `infra.rustic` kombiniert werden. Ihre `data_protect`-Aktionen können nur `files.copy` verwenden.
+
+## Netzwerk
+
+### `network.caddy`
+
+```yaml
+network:
+ caddy:
+ enabled: true
+ source: Caddyfile
+```
+
+| Schlüssel | Typ | Erforderlich | Beschreibung |
+|-----|------|----------|-------------|
+| `enabled` | `bool` | Nein | Aktiviert die Caddy-Verwaltung. Standardmäßig `false`. |
+| `source` | `string` | Bed. | Caddyfile-Pfad relativ zum Dienstverzeichnis. Erforderlich, wenn aktiviert. |
+
+### `network.dns`
+
+```yaml
+network:
+ dns:
+ provider: cloudflare
+ hostname: app.example.com
+ record_type: A
+ value: 203.0.113.10
+ proxied: true
+ ttl: 120
+ comment: Verwaltet von Composia
+```
+
+| Schlüssel | Typ | Erforderlich | Beschreibung |
+|-----|------|----------|-------------|
+| `provider` | `string` | Ja | `cloudflare`, `alidns`, `dnspod`, `route53` oder `huaweicloud`. |
+| `hostname` | `string` | Ja | DNS-Hostname. |
+| `record_type` | `string` | Nein | Leer, `A`, `AAAA` oder `CNAME`. |
+| `value` | `string` | Nein | DNS-Record-Wert. Multi-Node-Dienste sollten diesen explizit setzen. |
+| `proxied` | `bool` | Nein | Provider-spezifischer Proxy-Umschalter, derzeit relevant für Cloudflare. |
+| `ttl` | `uint32` | Nein | DNS-TTL. |
+| `comment` | `string` | Nein | DNS-Record-Kommentar. |
+
+## Image-Updates
+
+```yaml
+update:
+ enabled: true
+ auto_apply: false
+ check_schedule: "0 */6 * * *"
+ backup_before_update: true
+ digest_pin: false
+ backup_data:
+ - name: db
+ enabled: true
+ discovery_sources:
+ upstream:
+ sources:
+ - type: github
+ repo: owner/repo
+ combine: first_success
+ include_prerelease: false
+ images:
+ app:
+ image: ghcr.io/example/app
+ current:
+ env:
+ file: .env
+ key: APP_VERSION
+ discovery: upstream
+ filter:
+ type: semver
+ allow:
+ - patch
+ - minor
+```
+
+### `update`
+
+| Schlüssel | Typ | Beschreibung |
+|-----|------|-------------|
+| `enabled` | `bool` | Aktiviert Update-Prüfungen für diesen Dienst. |
+| `auto_apply` | `bool` | Wendet erkannte Updates automatisch an. |
+| `check_schedule` | `string` | Cron-Zeitplan für Update-Prüfungen. |
+| `backup_before_update` | `bool` | Führt Backups vor dem Anwenden von Updates aus. |
+| `backup_data` | `[]object` | Geschützte Datenelemente, die vor dem Update gesichert werden sollen. |
+| `digest_pin` | `bool` | Fixiert Images per Digest. |
+| `discovery_sources` | `map[string]object` | Wiederverwendbare Erkennungsquellen. Benannte Quellen können nicht auf eine andere Quelle verweisen. |
+| `images` | `map[string]object` | Update-Definitionen pro Image. |
+
+### `update.backup_data[]`
+
+| Schlüssel | Typ | Beschreibung |
+|-----|------|-------------|
+| `name` | `string` | Name des geschützten Datenelements. |
+| `enabled` | `bool` | Dieses Element ein- oder ausschließen. |
+
+### `update.images.`
+
+| Schlüssel | Typ | Erforderlich | Beschreibung |
+|-----|------|----------|-------------|
+| `image` | `string` | Ja | Image-Repository. |
+| `auto_apply` | `bool` | Nein | Per-Image-Override für automatisches Anwenden. |
+| `check_schedule` | `string` | Nein | Per-Image-Prüfzeitplan. |
+| `backup_before_update` | `bool` | Nein | Per-Image-Backup-Umschalter. |
+| `digest_pin` | `bool` | Nein | Per-Image-Digest-Pin-Umschalter. |
+| `current` | `object` | Ja | Aktuelle Versionsquelle. |
+| `discovery` | `object` oder `string` | Ja | Erkennungskonfiguration oder benannte Erkennungsquellenreferenz. |
+| `filter` | `object` | Bed. | Erforderlich, es sei denn, die Erkennung ist `digest`. |
+
+### `current`
+
+Gib genau eines davon an:
+
+| Schlüssel | Beschreibung |
+|-----|-------------|
+| `tag` | Statischer aktueller Tag. |
+| `env.file` + `env.key` | Liest den aktuellen Tag aus einer Env-Datei. `file` muss relativ sein und innerhalb des Dienstverzeichnisses bleiben. |
+| `yaml.file` + `yaml.path` | Liest den aktuellen Tag aus einer YAML-Datei. `file` muss relativ sein und innerhalb des Dienstverzeichnisses bleiben. |
+
+### `discovery`
+
+| Schlüssel | Typ | Beschreibung |
+|-----|------|-------------|
+| `sources` | `[]object` | Mindestens eine Quelle. |
+| `combine` | `string` | Leer, `merge` oder `first_success`. |
+| `include_prerelease` | `bool` | Vorabversionen einschließen. |
+
+Erkennungsquellentypen:
+
+| Typ | Erforderliche Schlüssel | Hinweise |
+|------|---------------|-------|
+| `auto` | Keine | `repo_url` ist optional und muss, wenn gesetzt, eine gültige URL sein. Muss die einzige Quelle sein. |
+| `probe` | Keine | Erfordert `semver`-Filter, wenn ein Filter vorhanden ist. |
+| `registry` | Keine | Registry-Tag-Erkennung. |
+| `digest` | Keine | Muss die einzige Quelle sein. `filter` muss weggelassen werden. |
+| `github` | `repo` | `repo` ist `owner/repo`. |
+| `gitlab` | `project` | GitLab-Projekt-ID oder -Pfad. |
+| `forgejo` | `repo` | `repo` ist `owner/repo`. |
+
+### `filter`
+
+| Typ | Erforderliche Schlüssel | Hinweise |
+|------|---------------|-------|
+| `semver` | Keine | `allow` kann `patch`, `minor`, `major` enthalten. |
+| `date` | `format` | Datumsformat zum Parsen von Tags. |
+| `regex` | `pattern`, `order` | `order` muss `numeric` oder `lexicographic` sein. |
+| `latest` | Keine | Verwendet den neuesten Kandidaten. |
+
+## Datenschutz
+
+```yaml
+data_protect:
+ data:
+ - name: db
+ backup:
+ strategy: database.pgdumpall
+ service: postgres
+ restore:
+ strategy: database.pgimport
+ service: postgres
+ - name: uploads
+ backup:
+ strategy: files.copy_after_stop
+ include:
+ - ./uploads
+ restore:
+ strategy: files.copy
+ include:
+ - ./uploads
+```
+
+### `data_protect.data[]`
+
+| Schlüssel | Typ | Erforderlich | Beschreibung |
+|-----|------|----------|-------------|
+| `name` | `string` | Ja | Eindeutiger Name des Datenelements. |
+| `backup` | `object` | Nein | Backup-Aktion. |
+| `restore` | `object` | Nein | Restore-Aktion. |
+
+### Datenaktion
+
+| Schlüssel | Typ | Erforderlich | Beschreibung |
+|-----|------|----------|-------------|
+| `strategy` | `string` | Ja | `files.copy`, `files.copy_after_stop`, `database.pgdumpall` oder `database.pgimport`. |
+| `service` | `string` | Bed. | Erforderlich für `database.*`-Strategien. Name des Compose-Dienstes. |
+| `include` | `[]string` | Bed. | Erforderlich für `files.*`-Strategien. |
+
+## Backups
+
+```yaml
+backup:
+ data:
+ - name: db
+ provider: rustic
+ enabled: true
+ schedule: "0 2 * * *"
+```
+
+| Schlüssel | Typ | Erforderlich | Beschreibung |
+|-----|------|----------|-------------|
+| `name` | `string` | Ja | Muss auf einen `data_protect.data[].name` mit einer Backup-Aktion verweisen. |
+| `provider` | `string` | Nein | Name des Backup-Providers. |
+| `enabled` | `bool` | Nein | Aktiviert oder deaktiviert diesen Backup-Eintrag. |
+| `schedule` | `string` | Nein | Cron-Zeitplan. |
+
+## Migration
+
+```yaml
+migrate:
+ data:
+ - name: db
+ enabled: true
+```
+
+| Schlüssel | Typ | Erforderlich | Beschreibung |
+|-----|------|----------|-------------|
+| `name` | `string` | Ja | Muss auf einen `data_protect.data[].name` mit sowohl Backup- als auch Restore-Aktionen verweisen. |
+| `enabled` | `bool` | Nein | Aktiviert oder deaktiviert die Migration für dieses Element. |
diff --git a/site/content/docs/guide/service.fr.md b/site/content/docs/guide/service.fr.md
new file mode 100644
index 0000000..7f6b977
--- /dev/null
+++ b/site/content/docs/guide/service.fr.md
@@ -0,0 +1,308 @@
+---
+title: "Configuration des services"
+date: '2026-05-26T00:00:00+08:00'
+weight: 10
+---
+
+Chaque service réside dans un répertoire à l'intérieur du dépôt du contrôleur. Un répertoire de service contient `composia-meta.yaml` et un ou plusieurs fichiers Docker Compose.
+
+Service minimal :
+
+```yaml {filename="composia-meta.yaml"}
+name: my-app
+nodes:
+ - main
+```
+
+Avec le comportement par défaut, Composia cherche `docker-compose.yaml` dans le même répertoire.
+
+## Clés de niveau supérieur
+
+| Clé | Type | Requis | Description |
+|-----|------|----------|-------------|
+| `name` | `string` | Oui | Nom unique du service. |
+| `project_name` | `string` | Non | Remplacement du nom de projet Docker Compose. Par défaut, un nom de service normalisé. |
+| `compose_files` | `[]string` | Non | Chemins des fichiers Compose relatifs au répertoire du service. |
+| `enabled` | `bool` | Non | Si le service est actif. Par défaut `true`. |
+| `nodes` | `[]string` | Oui | IDs des nœuds cibles. Chacun doit exister dans `controller.nodes`. |
+| `infra` | `object` | Non | Déclare ce service comme infrastructure Caddy, Rustic ou config-only. |
+| `network` | `object` | Non | Paramètres Caddy et DNS. |
+| `update` | `object` | Non | Paramètres de mise à jour d'images. |
+| `data_protect` | `object` | Non | Définitions de données de sauvegarde et de restauration. |
+| `backup` | `object` | Non | Sauvegardes planifiées pour les données protégées. |
+| `migrate` | `object` | Non | Données protégées activées pour la migration. |
+| `auto_deploy` | `bool` | Non | Déployer automatiquement ce service après des modifications du dépôt. |
+
+Les entrées `compose_files` doivent être des chemins relatifs, doivent rester à l'intérieur du répertoire du service et ne doivent pas être dupliquées.
+
+## Services d'infrastructure
+
+### `infra.caddy`
+
+Déclare le service d'infrastructure Caddy du dépôt.
+
+```yaml
+infra:
+ caddy:
+ compose_service: caddy
+ config_dir: /etc/caddy
+```
+
+| Clé | Type | Description |
+|-----|------|-------------|
+| `compose_service` | `string` | Nom du service Compose. Par défaut `caddy`. |
+| `config_dir` | `string` | Répertoire de configuration Caddy. Par défaut `/etc/caddy`. |
+
+Un seul service peut être déclaré comme infrastructure Caddy.
+
+### `infra.rustic`
+
+Déclare le service d'infrastructure Rustic du dépôt.
+
+```yaml
+infra:
+ rustic:
+ compose_service: rustic
+ profile: default
+ data_protect_dir: /data-protect
+ init_args:
+ - --set-version
+ - "2"
+```
+
+| Clé | Type | Description |
+|-----|------|-------------|
+| `compose_service` | `string` | Nom du service Compose. Par défaut `rustic`. |
+| `profile` | `string` | Nom du profil Rustic. |
+| `data_protect_dir` | `string` | Répertoire utilisé par les workflows de protection des données. |
+| `init_args` | `[]string` | Arguments supplémentaires passés à `rustic init`. Les entrées vides sont rejetées. |
+
+Un seul service peut être déclaré comme infrastructure Rustic.
+
+### `infra.config`
+
+Déclare un service d'infrastructure de configuration uniquement.
+
+```yaml
+infra:
+ config: {}
+```
+
+Les services config-only ne peuvent pas être combinés avec `infra.caddy` ou `infra.rustic`. Leurs actions `data_protect` ne peuvent utiliser que `files.copy`.
+
+## Réseau
+
+### `network.caddy`
+
+```yaml
+network:
+ caddy:
+ enabled: true
+ source: Caddyfile
+```
+
+| Clé | Type | Requis | Description |
+|-----|------|----------|-------------|
+| `enabled` | `bool` | Non | Active la gestion Caddy. Par défaut `false`. |
+| `source` | `string` | Cond. | Chemin du Caddyfile relatif au répertoire du service. Requis lorsque activé. |
+
+### `network.dns`
+
+```yaml
+network:
+ dns:
+ provider: cloudflare
+ hostname: app.example.com
+ record_type: A
+ value: 203.0.113.10
+ proxied: true
+ ttl: 120
+ comment: Managed by Composia
+```
+
+| Clé | Type | Requis | Description |
+|-----|------|----------|-------------|
+| `provider` | `string` | Oui | `cloudflare`, `alidns`, `dnspod`, `route53` ou `huaweicloud`. |
+| `hostname` | `string` | Oui | Nom d'hôte DNS. |
+| `record_type` | `string` | Non | Vide, `A`, `AAAA` ou `CNAME`. |
+| `value` | `string` | Non | Valeur de l'enregistrement DNS. Les services multi-nœuds devraient le définir explicitement. |
+| `proxied` | `bool` | Non | Bascule de proxy spécifique au fournisseur, actuellement pertinent pour Cloudflare. |
+| `ttl` | `uint32` | Non | TTL DNS. |
+| `comment` | `string` | Non | Commentaire de l'enregistrement DNS. |
+
+## Mises à jour d'images
+
+```yaml
+update:
+ enabled: true
+ auto_apply: false
+ check_schedule: "0 */6 * * *"
+ backup_before_update: true
+ digest_pin: false
+ backup_data:
+ - name: db
+ enabled: true
+ discovery_sources:
+ upstream:
+ sources:
+ - type: github
+ repo: owner/repo
+ combine: first_success
+ include_prerelease: false
+ images:
+ app:
+ image: ghcr.io/example/app
+ current:
+ env:
+ file: .env
+ key: APP_VERSION
+ discovery: upstream
+ filter:
+ type: semver
+ allow:
+ - patch
+ - minor
+```
+
+### `update`
+
+| Clé | Type | Description |
+|-----|------|-------------|
+| `enabled` | `bool` | Active les vérifications de mise à jour pour ce service. |
+| `auto_apply` | `bool` | Applique automatiquement les mises à jour détectées. |
+| `check_schedule` | `string` | Planification cron pour les vérifications de mise à jour. |
+| `backup_before_update` | `bool` | Exécute des sauvegardes avant d'appliquer les mises à jour. |
+| `backup_data` | `[]object` | Éléments de données protégés à sauvegarder avant la mise à jour. |
+| `digest_pin` | `bool` | Épingler les images par empreinte. |
+| `discovery_sources` | `map[string]object` | Sources de découverte réutilisables. Les sources nommées ne peuvent pas référencer une autre source. |
+| `images` | `map[string]object` | Définitions de mise à jour par image. |
+
+### `update.backup_data[]`
+
+| Clé | Type | Description |
+|-----|------|-------------|
+| `name` | `string` | Nom de l'élément de données protégé. |
+| `enabled` | `bool` | Inclure ou exclure cet élément. |
+
+### `update.images.`
+
+| Clé | Type | Requis | Description |
+|-----|------|----------|-------------|
+| `image` | `string` | Oui | Dépôt d'image. |
+| `auto_apply` | `bool` | Non | Remplacement auto-apply par image. |
+| `check_schedule` | `string` | Non | Planification de vérification par image. |
+| `backup_before_update` | `bool` | Non | Activation de la sauvegarde par image. |
+| `digest_pin` | `bool` | Non | Activation de l'épinglage par empreinte par image. |
+| `current` | `object` | Oui | Source de la version actuelle. |
+| `discovery` | `object` ou `string` | Oui | Configuration de découverte ou référence à une source de découverte nommée. |
+| `filter` | `object` | Cond. | Requis sauf si la découverte est `digest`. |
+
+### `current`
+
+Spécifiez exactement l'une des options suivantes :
+
+| Clé | Description |
+|-----|-------------|
+| `tag` | Balise actuelle statique. |
+| `env.file` + `env.key` | Lire la balise actuelle depuis un fichier d'environnement. `file` doit être relatif et rester à l'intérieur du répertoire du service. |
+| `yaml.file` + `yaml.path` | Lire la balise actuelle depuis un fichier YAML. `file` doit être relatif et rester à l'intérieur du répertoire du service. |
+
+### `discovery`
+
+| Clé | Type | Description |
+|-----|------|-------------|
+| `sources` | `[]object` | Au moins une source. |
+| `combine` | `string` | Vide, `merge` ou `first_success`. |
+| `include_prerelease` | `bool` | Inclure les versions préliminaires. |
+
+Types de sources de découverte :
+
+| Type | Clés requises | Notes |
+|------|---------------|-------|
+| `auto` | Aucune | `repo_url` est optionnel et doit être une URL valide si défini. Doit être la seule source. |
+| `probe` | Aucune | Nécessite un filtre `semver` lorsqu'un filtre est présent. |
+| `registry` | Aucune | Découverte des balises du registre. |
+| `digest` | Aucune | Doit être la seule source. `filter` doit être omis. |
+| `github` | `repo` | `repo` est `owner/repo`. |
+| `gitlab` | `project` | ID ou chemin du projet GitLab. |
+| `forgejo` | `repo` | `repo` est `owner/repo`. |
+
+### `filter`
+
+| Type | Clés requises | Notes |
+|------|---------------|-------|
+| `semver` | Aucune | `allow` peut contenir `patch`, `minor`, `major`. |
+| `date` | `format` | Format de date utilisé pour analyser les balises. |
+| `regex` | `pattern`, `order` | `order` doit être `numeric` ou `lexicographic`. |
+| `latest` | Aucune | Utilise le dernier candidat. |
+
+## Protection des données
+
+```yaml
+data_protect:
+ data:
+ - name: db
+ backup:
+ strategy: database.pgdumpall
+ service: postgres
+ restore:
+ strategy: database.pgimport
+ service: postgres
+ - name: uploads
+ backup:
+ strategy: files.copy_after_stop
+ include:
+ - ./uploads
+ restore:
+ strategy: files.copy
+ include:
+ - ./uploads
+```
+
+### `data_protect.data[]`
+
+| Clé | Type | Requis | Description |
+|-----|------|----------|-------------|
+| `name` | `string` | Oui | Nom unique de l'élément de données. |
+| `backup` | `object` | Non | Action de sauvegarde. |
+| `restore` | `object` | Non | Action de restauration. |
+
+### Action de données
+
+| Clé | Type | Requis | Description |
+|-----|------|----------|-------------|
+| `strategy` | `string` | Oui | `files.copy`, `files.copy_after_stop`, `database.pgdumpall` ou `database.pgimport`. |
+| `service` | `string` | Cond. | Requis pour les stratégies `database.*`. Nom du service Compose. |
+| `include` | `[]string` | Cond. | Requis pour les stratégies `files.*`. |
+
+## Sauvegardes
+
+```yaml
+backup:
+ data:
+ - name: db
+ provider: rustic
+ enabled: true
+ schedule: "0 2 * * *"
+```
+
+| Clé | Type | Requis | Description |
+|-----|------|----------|-------------|
+| `name` | `string` | Oui | Doit référencer un `data_protect.data[].name` avec une action de sauvegarde. |
+| `provider` | `string` | Non | Nom du fournisseur de sauvegarde. |
+| `enabled` | `bool` | Non | Activer ou désactiver cette entrée de sauvegarde. |
+| `schedule` | `string` | Non | Planification cron. |
+
+## Migration
+
+```yaml
+migrate:
+ data:
+ - name: db
+ enabled: true
+```
+
+| Clé | Type | Requis | Description |
+|-----|------|----------|-------------|
+| `name` | `string` | Oui | Doit référencer un `data_protect.data[].name` avec les deux actions de sauvegarde et de restauration. |
+| `enabled` | `bool` | Non | Activer ou désactiver la migration pour cet élément. |
diff --git a/site/content/docs/guide/service.ja.md b/site/content/docs/guide/service.ja.md
new file mode 100644
index 0000000..50ef0a8
--- /dev/null
+++ b/site/content/docs/guide/service.ja.md
@@ -0,0 +1,308 @@
+---
+title: "サービス設定"
+date: '2026-05-26T00:00:00+08:00'
+weight: 10
+---
+
+各サービスはコントローラーリポジトリ内のディレクトリに存在します。サービスディレクトリには `composia-meta.yaml` と 1 つ以上の Docker Compose ファイルが含まれます。
+
+最小限のサービス:
+
+```yaml {filename="composia-meta.yaml"}
+name: my-app
+nodes:
+ - main
+```
+
+デフォルトの動作では、Composia は同じディレクトリ内の `docker-compose.yaml` を探します。
+
+## トップレベルキー
+
+| キー | 型 | 必須 | 説明 |
+|-----|------|----------|-------------|
+| `name` | `string` | はい | 一意のサービス名。 |
+| `project_name` | `string` | いいえ | Docker Compose プロジェクト名の上書き。デフォルトは正規化されたサービス名。 |
+| `compose_files` | `[]string` | いいえ | サービスディレクトリからの相対 Compose ファイルパス。 |
+| `enabled` | `bool` | いいえ | サービスがアクティブかどうか。デフォルトは `true`。 |
+| `nodes` | `[]string` | はい | ターゲットノード ID。それぞれ `controller.nodes` に存在する必要があります。 |
+| `infra` | `object` | いいえ | このサービスを Caddy、Rustic、または config-only インフラストラクチャとして宣言します。 |
+| `network` | `object` | いいえ | Caddy と DNS の設定。 |
+| `update` | `object` | いいえ | イメージ更新設定。 |
+| `data_protect` | `object` | いいえ | バックアップとリストアのデータ定義。 |
+| `backup` | `object` | いいえ | 保護データのスケジュールバックアップ。 |
+| `migrate` | `object` | いいえ | 移行が有効な保護データ。 |
+| `auto_deploy` | `bool` | いいえ | リポジトリ変更後にこのサービスを自動デプロイします。 |
+
+`compose_files` エントリは相対パスで、サービスディレクトリ内に留まり、重複してはいけません。
+
+## インフラストラクチャサービス
+
+### `infra.caddy`
+
+リポジトリの Caddy インフラストラクチャサービスを宣言します。
+
+```yaml
+infra:
+ caddy:
+ compose_service: caddy
+ config_dir: /etc/caddy
+```
+
+| キー | 型 | 説明 |
+|-----|------|-------------|
+| `compose_service` | `string` | Compose サービス名。デフォルトは `caddy`。 |
+| `config_dir` | `string` | Caddy 設定ディレクトリ。デフォルトは `/etc/caddy`。 |
+
+Caddy インフラストラクチャとして宣言できるサービスは 1 つだけです。
+
+### `infra.rustic`
+
+リポジトリの Rustic インフラストラクチャサービスを宣言します。
+
+```yaml
+infra:
+ rustic:
+ compose_service: rustic
+ profile: default
+ data_protect_dir: /data-protect
+ init_args:
+ - --set-version
+ - "2"
+```
+
+| キー | 型 | 説明 |
+|-----|------|-------------|
+| `compose_service` | `string` | Compose サービス名。デフォルトは `rustic`。 |
+| `profile` | `string` | Rustic プロファイル名。 |
+| `data_protect_dir` | `string` | データ保護ワークフローで使用されるディレクトリ。 |
+| `init_args` | `[]string` | `rustic init` に渡される追加引数。空のエントリは拒否されます。 |
+
+Rustic インフラストラクチャとして宣言できるサービスは 1 つだけです。
+
+### `infra.config`
+
+config-only インフラストラクチャサービスを宣言します。
+
+```yaml
+infra:
+ config: {}
+```
+
+Config-only サービスは `infra.caddy` または `infra.rustic` と組み合わせることはできません。その `data_protect` アクションは `files.copy` のみ使用できます。
+
+## ネットワーク
+
+### `network.caddy`
+
+```yaml
+network:
+ caddy:
+ enabled: true
+ source: Caddyfile
+```
+
+| キー | 型 | 必須 | 説明 |
+|-----|------|----------|-------------|
+| `enabled` | `bool` | いいえ | Caddy 管理を有効にします。デフォルトは `false`。 |
+| `source` | `string` | 条件付き | サービスディレクトリからの相対 Caddyfile パス。有効時に必須。 |
+
+### `network.dns`
+
+```yaml
+network:
+ dns:
+ provider: cloudflare
+ hostname: app.example.com
+ record_type: A
+ value: 203.0.113.10
+ proxied: true
+ ttl: 120
+ comment: Managed by Composia
+```
+
+| キー | 型 | 必須 | 説明 |
+|-----|------|----------|-------------|
+| `provider` | `string` | はい | `cloudflare`、`alidns`、`dnspod`、`route53`、`huaweicloud` のいずれか。 |
+| `hostname` | `string` | はい | DNS ホスト名。 |
+| `record_type` | `string` | いいえ | 空、`A`、`AAAA`、`CNAME`。 |
+| `value` | `string` | いいえ | DNS レコード値。マルチノードサービスは明示的に設定することを推奨します。 |
+| `proxied` | `bool` | いいえ | プロバイダー固有のプロキシトグル。現在は Cloudflare に関連します。 |
+| `ttl` | `uint32` | いいえ | DNS TTL。 |
+| `comment` | `string` | いいえ | DNS レコードコメント。 |
+
+## イメージ更新
+
+```yaml
+update:
+ enabled: true
+ auto_apply: false
+ check_schedule: "0 */6 * * *"
+ backup_before_update: true
+ digest_pin: false
+ backup_data:
+ - name: db
+ enabled: true
+ discovery_sources:
+ upstream:
+ sources:
+ - type: github
+ repo: owner/repo
+ combine: first_success
+ include_prerelease: false
+ images:
+ app:
+ image: ghcr.io/example/app
+ current:
+ env:
+ file: .env
+ key: APP_VERSION
+ discovery: upstream
+ filter:
+ type: semver
+ allow:
+ - patch
+ - minor
+```
+
+### `update`
+
+| キー | 型 | 説明 |
+|-----|------|-------------|
+| `enabled` | `bool` | このサービスの更新チェックを有効にします。 |
+| `auto_apply` | `bool` | 検出された更新を自動的に適用します。 |
+| `check_schedule` | `string` | 更新チェックの cron スケジュール。 |
+| `backup_before_update` | `bool` | 更新を適用する前にバックアップを実行します。 |
+| `backup_data` | `[]object` | 更新前にバックアップする保護データ項目。 |
+| `digest_pin` | `bool` | イメージをダイジェストで固定します。 |
+| `discovery_sources` | `map[string]object` | 再利用可能な検出ソース。名前付きソースは別のソースを参照できません。 |
+| `images` | `map[string]object` | イメージごとの更新定義。 |
+
+### `update.backup_data[]`
+
+| キー | 型 | 説明 |
+|-----|------|-------------|
+| `name` | `string` | 保護データ項目名。 |
+| `enabled` | `bool` | この項目を含めるか除外するか。 |
+
+### `update.images.`
+
+| キー | 型 | 必須 | 説明 |
+|-----|------|----------|-------------|
+| `image` | `string` | はい | イメージリポジトリ。 |
+| `auto_apply` | `bool` | いいえ | イメージごとの自動適用の上書き。 |
+| `check_schedule` | `string` | いいえ | イメージごとのチェックスケジュール。 |
+| `backup_before_update` | `bool` | いいえ | イメージごとのバックアップトグル。 |
+| `digest_pin` | `bool` | いいえ | イメージごとのダイジェスト固定トグル。 |
+| `current` | `object` | はい | 現在のバージョンソース。 |
+| `discovery` | `object` または `string` | はい | 検出設定または名前付き検出ソース参照。 |
+| `filter` | `object` | 条件付き | 検出が `digest` でない限り必須。 |
+
+### `current`
+
+以下のいずれか 1 つを指定します:
+
+| キー | 説明 |
+|-----|-------------|
+| `tag` | 静的な現在のタグ。 |
+| `env.file` + `env.key` | env ファイルから現在のタグを読み取ります。`file` は相対パスでサービスディレクトリ内に留まる必要があります。 |
+| `yaml.file` + `yaml.path` | YAML ファイルから現在のタグを読み取ります。`file` は相対パスでサービスディレクトリ内に留まる必要があります。 |
+
+### `discovery`
+
+| キー | 型 | 説明 |
+|-----|------|-------------|
+| `sources` | `[]object` | 少なくとも 1 つのソース。 |
+| `combine` | `string` | 空、`merge`、`first_success`。 |
+| `include_prerelease` | `bool` | プレリリースバージョンを含めます。 |
+
+検出ソースタイプ:
+
+| タイプ | 必須キー | 注意事項 |
+|------|---------------|-------|
+| `auto` | なし | `repo_url` はオプションで、設定する場合は有効な URL である必要があります。唯一のソースである必要があります。 |
+| `probe` | なし | フィルターが存在する場合、`semver` フィルターが必要です。 |
+| `registry` | なし | レジストリタグ検出。 |
+| `digest` | なし | 唯一のソースである必要があります。`filter` は省略する必要があります。 |
+| `github` | `repo` | `repo` は `owner/repo` 形式。 |
+| `gitlab` | `project` | GitLab プロジェクト ID またはパス。 |
+| `forgejo` | `repo` | `repo` は `owner/repo` 形式。 |
+
+### `filter`
+
+| タイプ | 必須キー | 注意事項 |
+|------|---------------|-------|
+| `semver` | なし | `allow` には `patch`、`minor`、`major` を含められます。 |
+| `date` | `format` | タグの解析に使用される日付フォーマット。 |
+| `regex` | `pattern`, `order` | `order` は `numeric` または `lexicographic` である必要があります。 |
+| `latest` | なし | 最新の候補を使用します。 |
+
+## データ保護
+
+```yaml
+data_protect:
+ data:
+ - name: db
+ backup:
+ strategy: database.pgdumpall
+ service: postgres
+ restore:
+ strategy: database.pgimport
+ service: postgres
+ - name: uploads
+ backup:
+ strategy: files.copy_after_stop
+ include:
+ - ./uploads
+ restore:
+ strategy: files.copy
+ include:
+ - ./uploads
+```
+
+### `data_protect.data[]`
+
+| キー | 型 | 必須 | 説明 |
+|-----|------|----------|-------------|
+| `name` | `string` | はい | 一意のデータ項目名。 |
+| `backup` | `object` | いいえ | バックアップアクション。 |
+| `restore` | `object` | いいえ | リストアアクション。 |
+
+### データアクション
+
+| キー | 型 | 必須 | 説明 |
+|-----|------|----------|-------------|
+| `strategy` | `string` | はい | `files.copy`、`files.copy_after_stop`、`database.pgdumpall`、`database.pgimport`。 |
+| `service` | `string` | 条件付き | `database.*` 戦略で必須。Compose サービス名。 |
+| `include` | `[]string` | 条件付き | `files.*` 戦略で必須。 |
+
+## バックアップ
+
+```yaml
+backup:
+ data:
+ - name: db
+ provider: rustic
+ enabled: true
+ schedule: "0 2 * * *"
+```
+
+| キー | 型 | 必須 | 説明 |
+|-----|------|----------|-------------|
+| `name` | `string` | はい | バックアップアクションを持つ `data_protect.data[].name` を参照する必要があります。 |
+| `provider` | `string` | いいえ | バックアッププロバイダー名。 |
+| `enabled` | `bool` | いいえ | このバックアップエントリを有効または無効にします。 |
+| `schedule` | `string` | いいえ | cron スケジュール。 |
+
+## 移行
+
+```yaml
+migrate:
+ data:
+ - name: db
+ enabled: true
+```
+
+| キー | 型 | 必須 | 説明 |
+|-----|------|----------|-------------|
+| `name` | `string` | はい | バックアップとリストアの両方のアクションを持つ `data_protect.data[].name` を参照する必要があります。 |
+| `enabled` | `bool` | いいえ | この項目の移行を有効または無効にします。 |
diff --git a/site/content/docs/guide/service.zh-hans.md b/site/content/docs/guide/service.zh-hans.md
new file mode 100644
index 0000000..6de8c0a
--- /dev/null
+++ b/site/content/docs/guide/service.zh-hans.md
@@ -0,0 +1,308 @@
+---
+title: "服务配置"
+date: '2026-05-26T00:00:00+08:00'
+weight: 10
+---
+
+每个服务位于控制器仓库的一个目录中。服务目录包含 `composia-meta.yaml` 和一个或多个 Docker Compose 文件。
+
+最小服务：
+
+```yaml {filename="composia-meta.yaml"}
+name: my-app
+nodes:
+ - main
+```
+
+在默认行为下，Composia 会在同一目录中查找 `docker-compose.yaml`。
+
+## 顶级键
+
+| 键 | 类型 | 必填 | 描述 |
+|-----|------|----------|-------------|
+| `name` | `string` | 是 | 唯一的服务名称。 |
+| `project_name` | `string` | 否 | Docker Compose 项目名称覆盖。默认为规范化后的服务名称。 |
+| `compose_files` | `[]string` | 否 | 相对于服务目录的 Compose 文件路径。 |
+| `enabled` | `bool` | 否 | 服务是否激活。默认为 `true`。 |
+| `nodes` | `[]string` | 是 | 目标节点 ID 列表。每个都必须存在于 `controller.nodes` 中。 |
+| `infra` | `object` | 否 | 声明此服务为 Caddy、Rustic 或仅配置型基础设施。 |
+| `network` | `object` | 否 | Caddy 和 DNS 设置。 |
+| `update` | `object` | 否 | 镜像更新设置。 |
+| `data_protect` | `object` | 否 | 备份和恢复数据定义。 |
+| `backup` | `object` | 否 | 受保护数据的定时备份。 |
+| `migrate` | `object` | 否 | 启用迁移的受保护数据。 |
+| `auto_deploy` | `bool` | 否 | 仓库更改后自动部署此服务。 |
+
+`compose_files` 条目必须是相对路径，必须保持在服务目录内，且不能重复。
+
+## 基础设施服务
+
+### `infra.caddy`
+
+声明仓库的 Caddy 基础设施服务。
+
+```yaml
+infra:
+ caddy:
+ compose_service: caddy
+ config_dir: /etc/caddy
+```
+
+| 键 | 类型 | 描述 |
+|-----|------|-------------|
+| `compose_service` | `string` | Compose 服务名称。默认为 `caddy`。 |
+| `config_dir` | `string` | Caddy 配置目录。默认为 `/etc/caddy`。 |
+
+只能有一个服务被声明为 Caddy 基础设施。
+
+### `infra.rustic`
+
+声明仓库的 Rustic 基础设施服务。
+
+```yaml
+infra:
+ rustic:
+ compose_service: rustic
+ profile: default
+ data_protect_dir: /data-protect
+ init_args:
+ - --set-version
+ - "2"
+```
+
+| 键 | 类型 | 描述 |
+|-----|------|-------------|
+| `compose_service` | `string` | Compose 服务名称。默认为 `rustic`。 |
+| `profile` | `string` | Rustic 配置文件名称。 |
+| `data_protect_dir` | `string` | 数据保护工作流使用的目录。 |
+| `init_args` | `[]string` | 传递给 `rustic init` 的额外参数。空条目会被拒绝。 |
+
+只能有一个服务被声明为 Rustic 基础设施。
+
+### `infra.config`
+
+声明一个仅配置型基础设施服务。
+
+```yaml
+infra:
+ config: {}
+```
+
+仅配置型服务不能与 `infra.caddy` 或 `infra.rustic` 组合。其 `data_protect` 操作只能使用 `files.copy`。
+
+## 网络
+
+### `network.caddy`
+
+```yaml
+network:
+ caddy:
+ enabled: true
+ source: Caddyfile
+```
+
+| 键 | 类型 | 必填 | 描述 |
+|-----|------|----------|-------------|
+| `enabled` | `bool` | 否 | 启用 Caddy 管理。默认为 `false`。 |
+| `source` | `string` | 条件 | 相对于服务目录的 Caddyfile 路径。启用时必填。 |
+
+### `network.dns`
+
+```yaml
+network:
+ dns:
+ provider: cloudflare
+ hostname: app.example.com
+ record_type: A
+ value: 203.0.113.10
+ proxied: true
+ ttl: 120
+ comment: 由 Composia 管理
+```
+
+| 键 | 类型 | 必填 | 描述 |
+|-----|------|----------|-------------|
+| `provider` | `string` | 是 | `cloudflare`、`alidns`、`dnspod`、`route53` 或 `huaweicloud`。 |
+| `hostname` | `string` | 是 | DNS 主机名。 |
+| `record_type` | `string` | 否 | 空、`A`、`AAAA` 或 `CNAME`。 |
+| `value` | `string` | 否 | DNS 记录值。多节点服务应显式设置此项。 |
+| `proxied` | `bool` | 否 | 提供商特定的代理开关，目前与 Cloudflare 相关。 |
+| `ttl` | `uint32` | 否 | DNS TTL。 |
+| `comment` | `string` | 否 | DNS 记录备注。 |
+
+## 镜像更新
+
+```yaml
+update:
+ enabled: true
+ auto_apply: false
+ check_schedule: "0 */6 * * *"
+ backup_before_update: true
+ digest_pin: false
+ backup_data:
+ - name: db
+ enabled: true
+ discovery_sources:
+ upstream:
+ sources:
+ - type: github
+ repo: owner/repo
+ combine: first_success
+ include_prerelease: false
+ images:
+ app:
+ image: ghcr.io/example/app
+ current:
+ env:
+ file: .env
+ key: APP_VERSION
+ discovery: upstream
+ filter:
+ type: semver
+ allow:
+ - patch
+ - minor
+```
+
+### `update`
+
+| 键 | 类型 | 描述 |
+|-----|------|-------------|
+| `enabled` | `bool` | 为此服务启用更新检查。 |
+| `auto_apply` | `bool` | 自动应用检测到的更新。 |
+| `check_schedule` | `string` | 更新检查的 cron 计划。 |
+| `backup_before_update` | `bool` | 在应用更新之前运行备份。 |
+| `backup_data` | `[]object` | 更新前要备份的受保护数据项。 |
+| `digest_pin` | `bool` | 通过摘要锁定镜像。 |
+| `discovery_sources` | `map[string]object` | 可复用的发现源。命名源不能引用另一个源。 |
+| `images` | `map[string]object` | 每镜像更新定义。 |
+
+### `update.backup_data[]`
+
+| 键 | 类型 | 描述 |
+|-----|------|-------------|
+| `name` | `string` | 受保护的数据项名称。 |
+| `enabled` | `bool` | 包含或排除此项。 |
+
+### `update.images.`
+
+| 键 | 类型 | 必填 | 描述 |
+|-----|------|----------|-------------|
+| `image` | `string` | 是 | 镜像仓库。 |
+| `auto_apply` | `bool` | 否 | 每镜像自动应用覆盖。 |
+| `check_schedule` | `string` | 否 | 每镜像检查计划。 |
+| `backup_before_update` | `bool` | 否 | 每镜像备份开关。 |
+| `digest_pin` | `bool` | 否 | 每镜像摘要锁定开关。 |
+| `current` | `object` | 是 | 当前版本来源。 |
+| `discovery` | `object` 或 `string` | 是 | 发现配置或命名发现源引用。 |
+| `filter` | `object` | 条件 | 必填，除非发现模式为 `digest`。 |
+
+### `current`
+
+指定以下之一：
+
+| 键 | 描述 |
+|-----|-------------|
+| `tag` | 静态当前标签。 |
+| `env.file` + `env.key` | 从环境变量文件读取当前标签。`file` 必须是相对路径且保持在服务目录内。 |
+| `yaml.file` + `yaml.path` | 从 YAML 文件读取当前标签。`file` 必须是相对路径且保持在服务目录内。 |
+
+### `discovery`
+
+| 键 | 类型 | 描述 |
+|-----|------|-------------|
+| `sources` | `[]object` | 至少一个源。 |
+| `combine` | `string` | 空、`merge` 或 `first_success`。 |
+| `include_prerelease` | `bool` | 包含预发布版本。 |
+
+发现源类型：
+
+| 类型 | 必填键 | 备注 |
+|------|---------------|-------|
+| `auto` | 无 | `repo_url` 可选，设置时必须为有效 URL。必须是唯一源。 |
+| `probe` | 无 | 当存在过滤器时需要 `semver` 过滤器。 |
+| `registry` | 无 | 注册表标签发现。 |
+| `digest` | 无 | 必须是唯一源。必须省略 `filter`。 |
+| `github` | `repo` | `repo` 格式为 `owner/repo`。 |
+| `gitlab` | `project` | GitLab 项目 ID 或路径。 |
+| `forgejo` | `repo` | `repo` 格式为 `owner/repo`。 |
+
+### `filter`
+
+| 类型 | 必填键 | 备注 |
+|------|---------------|-------|
+| `semver` | 无 | `allow` 可包含 `patch`、`minor`、`major`。 |
+| `date` | `format` | 用于解析标签的日期格式。 |
+| `regex` | `pattern`、`order` | `order` 必须为 `numeric` 或 `lexicographic`。 |
+| `latest` | 无 | 使用最新候选版本。 |
+
+## 数据保护
+
+```yaml
+data_protect:
+ data:
+ - name: db
+ backup:
+ strategy: database.pgdumpall
+ service: postgres
+ restore:
+ strategy: database.pgimport
+ service: postgres
+ - name: uploads
+ backup:
+ strategy: files.copy_after_stop
+ include:
+ - ./uploads
+ restore:
+ strategy: files.copy
+ include:
+ - ./uploads
+```
+
+### `data_protect.data[]`
+
+| 键 | 类型 | 必填 | 描述 |
+|-----|------|----------|-------------|
+| `name` | `string` | 是 | 唯一的数据项名称。 |
+| `backup` | `object` | 否 | 备份操作。 |
+| `restore` | `object` | 否 | 恢复操作。 |
+
+### 数据操作
+
+| 键 | 类型 | 必填 | 描述 |
+|-----|------|----------|-------------|
+| `strategy` | `string` | 是 | `files.copy`、`files.copy_after_stop`、`database.pgdumpall` 或 `database.pgimport`。 |
+| `service` | `string` | 条件 | `database.*` 策略必填。Compose 服务名称。 |
+| `include` | `[]string` | 条件 | `files.*` 策略必填。 |
+
+## 备份
+
+```yaml
+backup:
+ data:
+ - name: db
+ provider: rustic
+ enabled: true
+ schedule: "0 2 * * *"
+```
+
+| 键 | 类型 | 必填 | 描述 |
+|-----|------|----------|-------------|
+| `name` | `string` | 是 | 必须引用具有备份操作的 `data_protect.data[].name`。 |
+| `provider` | `string` | 否 | 备份提供者名称。 |
+| `enabled` | `bool` | 否 | 启用或禁用此备份条目。 |
+| `schedule` | `string` | 否 | Cron 计划。 |
+
+## 迁移
+
+```yaml
+migrate:
+ data:
+ - name: db
+ enabled: true
+```
+
+| 键 | 类型 | 必填 | 描述 |
+|-----|------|----------|-------------|
+| `name` | `string` | 是 | 必须引用同时具有备份和恢复操作的 `data_protect.data[].name`。 |
+| `enabled` | `bool` | 否 | 启用或禁用此项的迁移。 |
diff --git a/site/content/docs/guide/service.zh-hant.md b/site/content/docs/guide/service.zh-hant.md
new file mode 100644
index 0000000..92b04e9
--- /dev/null
+++ b/site/content/docs/guide/service.zh-hant.md
@@ -0,0 +1,308 @@
+---
+title: "服務設定"
+date: '2026-05-26T00:00:00+08:00'
+weight: 10
+---
+
+每個服務位於控制器存放庫中的一個目錄內。服務目錄包含 `composia-meta.yaml` 和一個或多個 Docker Compose 檔案。
+
+最小服務：
+
+```yaml {filename="composia-meta.yaml"}
+name: my-app
+nodes:
+ - main
+```
+
+使用預設行為時，Composia 會在同一目錄中尋找 `docker-compose.yaml`。
+
+## 頂層鍵
+
+| 鍵 | 型別 | 必要 | 說明 |
+|-----|------|----------|-------------|
+| `name` | `string` | 是 | 唯一的服務名稱。 |
+| `project_name` | `string` | 否 | Docker Compose 專案名稱覆蓋。預設為正規化的服務名稱。 |
+| `compose_files` | `[]string` | 否 | Compose 檔案路徑，相對於服務目錄。 |
+| `enabled` | `bool` | 否 | 服務是否啟用。預設為 `true`。 |
+| `nodes` | `[]string` | 是 | 目標節點 ID。每個必須存在於 `controller.nodes` 中。 |
+| `infra` | `object` | 否 | 宣告此服務為 Caddy、Rustic 或純設定基礎架構。 |
+| `network` | `object` | 否 | Caddy 和 DNS 設定。 |
+| `update` | `object` | 否 | 映像檔更新設定。 |
+| `data_protect` | `object` | 否 | 備份和還原資料定義。 |
+| `backup` | `object` | 否 | 受保護資料的排程備份。 |
+| `migrate` | `object` | 否 | 啟用遷移的受保護資料。 |
+| `auto_deploy` | `bool` | 否 | 存放庫變更後自動部署此服務。 |
+
+`compose_files` 項目必須是相對路徑、必須保持在服務目錄內，且不得重複。
+
+## 基礎架構服務
+
+### `infra.caddy`
+
+宣告存放庫的 Caddy 基礎架構服務。
+
+```yaml
+infra:
+ caddy:
+ compose_service: caddy
+ config_dir: /etc/caddy
+```
+
+| 鍵 | 型別 | 說明 |
+|-----|------|-------------|
+| `compose_service` | `string` | Compose 服務名稱。預設為 `caddy`。 |
+| `config_dir` | `string` | Caddy 設定目錄。預設為 `/etc/caddy`。 |
+
+只有一個服務可以宣告為 Caddy 基礎架構。
+
+### `infra.rustic`
+
+宣告存放庫的 Rustic 基礎架構服務。
+
+```yaml
+infra:
+ rustic:
+ compose_service: rustic
+ profile: default
+ data_protect_dir: /data-protect
+ init_args:
+ - --set-version
+ - "2"
+```
+
+| 鍵 | 型別 | 說明 |
+|-----|------|-------------|
+| `compose_service` | `string` | Compose 服務名稱。預設為 `rustic`。 |
+| `profile` | `string` | Rustic 設定檔名稱。 |
+| `data_protect_dir` | `string` | 資料保護工作流程使用的目錄。 |
+| `init_args` | `[]string` | 傳遞給 `rustic init` 的額外參數。空白項目會被拒絕。 |
+
+只有一個服務可以宣告為 Rustic 基礎架構。
+
+### `infra.config`
+
+宣告一個純設定基礎架構服務。
+
+```yaml
+infra:
+ config: {}
+```
+
+純設定服務不能與 `infra.caddy` 或 `infra.rustic` 合併使用。它們的 `data_protect` 操作只能使用 `files.copy`。
+
+## 網路
+
+### `network.caddy`
+
+```yaml
+network:
+ caddy:
+ enabled: true
+ source: Caddyfile
+```
+
+| 鍵 | 型別 | 必要 | 說明 |
+|-----|------|----------|-------------|
+| `enabled` | `bool` | 否 | 啟用 Caddy 管理。預設為 `false`。 |
+| `source` | `string` | 條件必要 | Caddyfile 路徑，相對於服務目錄。啟用時為必要項。 |
+
+### `network.dns`
+
+```yaml
+network:
+ dns:
+ provider: cloudflare
+ hostname: app.example.com
+ record_type: A
+ value: 203.0.113.10
+ proxied: true
+ ttl: 120
+ comment: Managed by Composia
+```
+
+| 鍵 | 型別 | 必要 | 說明 |
+|-----|------|----------|-------------|
+| `provider` | `string` | 是 | `cloudflare`、`alidns`、`dnspod`、`route53` 或 `huaweicloud`。 |
+| `hostname` | `string` | 是 | DNS 主機名稱。 |
+| `record_type` | `string` | 否 | 空白、`A`、`AAAA` 或 `CNAME`。 |
+| `value` | `string` | 否 | DNS 記錄值。多節點服務應明確設定此項。 |
+| `proxied` | `bool` | 否 | 提供者特定的代理開關，目前與 Cloudflare 相關。 |
+| `ttl` | `uint32` | 否 | DNS TTL。 |
+| `comment` | `string` | 否 | DNS 記錄備註。 |
+
+## 映像檔更新
+
+```yaml
+update:
+ enabled: true
+ auto_apply: false
+ check_schedule: "0 */6 * * *"
+ backup_before_update: true
+ digest_pin: false
+ backup_data:
+ - name: db
+ enabled: true
+ discovery_sources:
+ upstream:
+ sources:
+ - type: github
+ repo: owner/repo
+ combine: first_success
+ include_prerelease: false
+ images:
+ app:
+ image: ghcr.io/example/app
+ current:
+ env:
+ file: .env
+ key: APP_VERSION
+ discovery: upstream
+ filter:
+ type: semver
+ allow:
+ - patch
+ - minor
+```
+
+### `update`
+
+| 鍵 | 型別 | 說明 |
+|-----|------|-------------|
+| `enabled` | `bool` | 為此服務啟用更新檢查。 |
+| `auto_apply` | `bool` | 自動套用偵測到的更新。 |
+| `check_schedule` | `string` | 更新檢查的 cron 排程。 |
+| `backup_before_update` | `bool` | 在套用更新前執行備份。 |
+| `backup_data` | `[]object` | 更新前要備份的受保護資料項目。 |
+| `digest_pin` | `bool` | 以摘要固定映像檔。 |
+| `discovery_sources` | `map[string]object` | 可重用的發現來源。具名來源不能引用另一個來源。 |
+| `images` | `map[string]object` | 每個映像檔的更新定義。 |
+
+### `update.backup_data[]`
+
+| 鍵 | 型別 | 說明 |
+|-----|------|-------------|
+| `name` | `string` | 受保護資料項目名稱。 |
+| `enabled` | `bool` | 包含或排除此項目。 |
+
+### `update.images.`
+
+| 鍵 | 型別 | 必要 | 說明 |
+|-----|------|----------|-------------|
+| `image` | `string` | 是 | 映像檔存放庫。 |
+| `auto_apply` | `bool` | 否 | 每個映像檔的自動套用覆蓋。 |
+| `check_schedule` | `string` | 否 | 每個映像檔的檢查排程。 |
+| `backup_before_update` | `bool` | 否 | 每個映像檔的備份開關。 |
+| `digest_pin` | `bool` | 否 | 每個映像檔的摘要固定開關。 |
+| `current` | `object` | 是 | 目前版本來源。 |
+| `discovery` | `object` 或 `string` | 是 | 發現設定或具名發現來源引用。 |
+| `filter` | `object` | 條件必要 | 除非發現為 `digest`，否則為必要項。 |
+
+### `current`
+
+恰好指定以下之一：
+
+| 鍵 | 說明 |
+|-----|-------------|
+| `tag` | 靜態目前標籤。 |
+| `env.file` + `env.key` | 從 env 檔案讀取目前標籤。`file` 必須是相對路徑且保持在服務目錄內。 |
+| `yaml.file` + `yaml.path` | 從 YAML 檔案讀取目前標籤。`file` 必須是相對路徑且保持在服務目錄內。 |
+
+### `discovery`
+
+| 鍵 | 型別 | 說明 |
+|-----|------|-------------|
+| `sources` | `[]object` | 至少一個來源。 |
+| `combine` | `string` | 空白、`merge` 或 `first_success`。 |
+| `include_prerelease` | `bool` | 包含預發行版本。 |
+
+發現來源型別：
+
+| 型別 | 必要鍵 | 備註 |
+|------|---------------|-------|
+| `auto` | 無 | `repo_url` 是可選的，若設定必須是有效 URL。必須是唯一來源。 |
+| `probe` | 無 | 當存在過濾器時需要 `semver` 過濾器。 |
+| `registry` | 無 | 登錄庫標籤發現。 |
+| `digest` | 無 | 必須是唯一來源。必須省略 `filter`。 |
+| `github` | `repo` | `repo` 為 `owner/repo`。 |
+| `gitlab` | `project` | GitLab 專案 ID 或路徑。 |
+| `forgejo` | `repo` | `repo` 為 `owner/repo`。 |
+
+### `filter`
+
+| 型別 | 必要鍵 | 備註 |
+|------|---------------|-------|
+| `semver` | 無 | `allow` 可包含 `patch`、`minor`、`major`。 |
+| `date` | `format` | 用於解析標籤的日期格式。 |
+| `regex` | `pattern`、`order` | `order` 必須為 `numeric` 或 `lexicographic`。 |
+| `latest` | 無 | 使用最新的候選項。 |
+
+## 資料保護
+
+```yaml
+data_protect:
+ data:
+ - name: db
+ backup:
+ strategy: database.pgdumpall
+ service: postgres
+ restore:
+ strategy: database.pgimport
+ service: postgres
+ - name: uploads
+ backup:
+ strategy: files.copy_after_stop
+ include:
+ - ./uploads
+ restore:
+ strategy: files.copy
+ include:
+ - ./uploads
+```
+
+### `data_protect.data[]`
+
+| 鍵 | 型別 | 必要 | 說明 |
+|-----|------|----------|-------------|
+| `name` | `string` | 是 | 唯一的資料項目名稱。 |
+| `backup` | `object` | 否 | 備份操作。 |
+| `restore` | `object` | 否 | 還原操作。 |
+
+### 資料操作
+
+| 鍵 | 型別 | 必要 | 說明 |
+|-----|------|----------|-------------|
+| `strategy` | `string` | 是 | `files.copy`、`files.copy_after_stop`、`database.pgdumpall` 或 `database.pgimport`。 |
+| `service` | `string` | 條件必要 | `database.*` 策略的必要項。Compose 服務名稱。 |
+| `include` | `[]string` | 條件必要 | `files.*` 策略的必要項。 |
+
+## 備份
+
+```yaml
+backup:
+ data:
+ - name: db
+ provider: rustic
+ enabled: true
+ schedule: "0 2 * * *"
+```
+
+| 鍵 | 型別 | 必要 | 說明 |
+|-----|------|----------|-------------|
+| `name` | `string` | 是 | 必須引用具有備份操作的 `data_protect.data[].name`。 |
+| `provider` | `string` | 否 | 備份提供者名稱。 |
+| `enabled` | `bool` | 否 | 啟用或停用此備份項目。 |
+| `schedule` | `string` | 否 | Cron 排程。 |
+
+## 遷移
+
+```yaml
+migrate:
+ data:
+ - name: db
+ enabled: true
+```
+
+| 鍵 | 型別 | 必要 | 說明 |
+|-----|------|----------|-------------|
+| `name` | `string` | 是 | 必須引用同時具有備份和還原操作的 `data_protect.data[].name`。 |
+| `enabled` | `bool` | 否 | 啟用或停用此項目的遷移。 |
diff --git a/site/content/docs/installation/_index.de.md b/site/content/docs/installation/_index.de.md
new file mode 100644
index 0000000..98bca6e
--- /dev/null
+++ b/site/content/docs/installation/_index.de.md
@@ -0,0 +1,24 @@
+---
+title: "Installation"
+date: '2026-05-26T00:00:00+08:00'
+weight: 10
+---
+
+Composia hat vier Laufzeit-Binärdateien und -Images:
+
+| Komponente | Zweck |
+|-----------|---------|
+| `composia-controller` | Führt die API, die Aufgabenwarteschlange, das Sollzustand-Git-Repository und controller-seitige Integrationen aus. |
+| `composia-agent` | Läuft auf jedem Docker-Node und führt Docker-Compose-Operationen aus. |
+| `composia-web` | Browser-UI, die mit dem Controller kommuniziert. |
+| `composia` | CLI für Terminals, Skripte und Automatisierung. |
+
+## Wähle eine Methode
+
+| Methode | Am besten für |
+|--------|----------|
+| [Docker Compose](docker-compose/) | Schnelle All-in-One-Bereitstellung mit Controller, lokalem Agent und Web-UI. |
+| [Paketmanager und Binärdateien](package-managers/) | Nicht-Container-Installationen, Betriebssystempakete, Nix, AUR und manuelle Archive. |
+| [Konfiguration](configuration/) | Konfigurationsdateien, Web-Umgebungsvariablen, Age-Schlüssel-Einrichtung und vollständige globale Konfigurationsreferenz. |
+
+Für Source-Builds siehe [Entwickler-Leitfaden: Source Build](/docs/developer-guide/source-build/).
diff --git a/site/content/docs/installation/_index.fr.md b/site/content/docs/installation/_index.fr.md
new file mode 100644
index 0000000..5d6eaec
--- /dev/null
+++ b/site/content/docs/installation/_index.fr.md
@@ -0,0 +1,24 @@
+---
+title: "Installation"
+date: '2026-05-26T00:00:00+08:00'
+weight: 10
+---
+
+Composia a quatre binaires et images d'exécution :
+
+| Composant | Rôle |
+|-----------|---------|
+| `composia-controller` | Exécute l'API, la file de tâches, le dépôt Git d'état désiré et les intégrations côté contrôleur. |
+| `composia-agent` | S'exécute sur chaque nœud Docker et exécute les opérations Docker Compose. |
+| `composia-web` | Interface navigateur qui communique avec le contrôleur. |
+| `composia` | CLI pour les terminaux, les scripts et l'automatisation. |
+
+## Choisir une méthode
+
+| Méthode | Idéale pour |
+|--------|----------|
+| [Docker Compose](docker-compose/) | Déploiement tout-en-un rapide avec contrôleur, agent local et interface web. |
+| [Gestionnaires de paquets et binaires](package-managers/) | Installations sans conteneur, paquets OS, Nix, AUR et archives manuelles. |
+| [Configuration](configuration/) | Fichiers de configuration, variables d'environnement web, configuration des clés age et référence complète de la configuration globale. |
+
+Pour les compilations depuis les sources, voir [Guide développeur : Build depuis les sources](/docs/developer-guide/source-build/).
diff --git a/site/content/docs/installation/_index.ja.md b/site/content/docs/installation/_index.ja.md
new file mode 100644
index 0000000..50b3631
--- /dev/null
+++ b/site/content/docs/installation/_index.ja.md
@@ -0,0 +1,24 @@
+---
+title: "インストール"
+date: '2026-05-26T00:00:00+08:00'
+weight: 10
+---
+
+Composia には 4 つのランタイムバイナリとイメージがあります:
+
+| コンポーネント | 目的 |
+|-----------|---------|
+| `composia-controller` | API、タスクキュー、期待状態 Git リポジトリ、コントローラー側の統合を実行します。 |
+| `composia-agent` | 各 Docker ノード上で実行され、Docker Compose 操作を実行します。 |
+| `composia-web` | コントローラーと通信するブラウザ UI。 |
+| `composia` | ターミナル、スクリプト、自動化のための CLI。 |
+
+## 方法の選択
+
+| 方法 | 最適な用途 |
+|--------|----------|
+| [Docker Compose](docker-compose/) | コントローラー、ローカルエージェント、Web UI を含む高速なオールインワンデプロイ。 |
+| [パッケージマネージャーとバイナリ](package-managers/) | 非コンテナインストール、OS パッケージ、Nix、AUR、手動アーカイブ。 |
+| [設定](configuration/) | 設定ファイル、Web 環境変数、age 鍵のセットアップ、完全なグローバル設定リファレンス。 |
+
+ソースビルドについては [開発者ガイド: ソースビルド](/docs/developer-guide/source-build/) を参照してください。
diff --git a/site/content/docs/installation/_index.zh-hans.md b/site/content/docs/installation/_index.zh-hans.md
new file mode 100644
index 0000000..c2eaf8c
--- /dev/null
+++ b/site/content/docs/installation/_index.zh-hans.md
@@ -0,0 +1,24 @@
+---
+title: "安装"
+date: '2026-05-26T00:00:00+08:00'
+weight: 10
+---
+
+Composia 有四个运行时二进制文件和镜像：
+
+| 组件 | 用途 |
+|-----------|---------|
+| `composia-controller` | 运行 API、任务队列、期望状态 Git 仓库以及控制器端集成。 |
+| `composia-agent` | 在每个 Docker 节点上运行，执行 Docker Compose 操作。 |
+| `composia-web` | 与控制器通信的浏览器 UI。 |
+| `composia` | 用于终端、脚本和自动化的 CLI。 |
+
+## 选择安装方式
+
+| 方式 | 适用场景 |
+|--------|----------|
+| [Docker Compose](docker-compose/) | 快速一体化部署，包含控制器、本地 agent 和 Web UI。 |
+| [包管理器与二进制文件](package-managers/) | 非容器安装、操作系统包、Nix、AUR 和手动下载归档。 |
+| [配置](configuration/) | 配置文件、Web 环境变量、age 密钥设置和完整的全局配置参考。 |
+
+对于源码构建，请参阅[开发者指南：源码构建](/docs/developer-guide/source-build/)。
diff --git a/site/content/docs/installation/_index.zh-hant.md b/site/content/docs/installation/_index.zh-hant.md
new file mode 100644
index 0000000..253d4ba
--- /dev/null
+++ b/site/content/docs/installation/_index.zh-hant.md
@@ -0,0 +1,24 @@
+---
+title: "安裝"
+date: '2026-05-26T00:00:00+08:00'
+weight: 10
+---
+
+Composia 有四個執行時期二進位檔和映像檔：
+
+| 元件 | 用途 |
+|-----------|---------|
+| `composia-controller` | 執行 API、任務佇列、期望狀態 Git 存放庫以及控制器端整合。 |
+| `composia-agent` | 在每個 Docker 節點上執行 Docker Compose 操作。 |
+| `composia-web` | 與控制器通訊的瀏覽器 UI。 |
+| `composia` | 用於終端機、腳本和自動化的 CLI。 |
+
+## 選擇安裝方式
+
+| 方式 | 最適合 |
+|--------|----------|
+| [Docker Compose](docker-compose/) | 快速的整合式部署，包含控制器、本地代理和 Web UI。 |
+| [套件管理器與二進位檔](package-managers/) | 非容器安裝、OS 套件、Nix、AUR 及手動壓縮檔。 |
+| [設定](configuration/) | 設定檔、Web 環境變數、age 金鑰設定與完整全域設定參考。 |
+
+如需原始碼建置，請參見[開發者指南：原始碼建置](/docs/developer-guide/source-build/)。
diff --git a/site/content/docs/installation/configuration.de.md b/site/content/docs/installation/configuration.de.md
new file mode 100644
index 0000000..fe1ba3b
--- /dev/null
+++ b/site/content/docs/installation/configuration.de.md
@@ -0,0 +1,457 @@
+---
+title: "Konfiguration"
+date: '2026-05-26T00:00:00+08:00'
+weight: 40
+---
+
+Diese Seite behandelt die installationsbezogene Konfiguration: Controller-Konfiguration, Agent-Konfiguration, Web-Umgebungsvariablen und Age-Schlüssel-Einrichtung.
+
+Dienstdefinitionen befinden sich in `composia-meta.yaml`. Siehe [Dienst-Leitfaden](/docs/guide/service/) für diese Datei.
+
+## Aufbau der Konfigurationsdatei
+
+Controller und Agent verwenden dasselbe YAML-Dateiformat. Eine Datei kann einen oder beide Abschnitte enthalten:
+
+```yaml
+controller:
+ # Controller-Einstellungen
+
+agent:
+ # Agent-Einstellungen
+```
+
+Mindestens einer von `controller` oder `agent` muss vorhanden sein.
+
+Wenn dieselbe Konfigurationsdatei beide Abschnitte enthält, wird der lokale Agent als eingebauter Node behandelt:
+
+- `agent.node_id` muss `main` sein.
+- `controller.nodes` muss einen Eintrag mit `id: main` enthalten.
+- `controller.repo_dir` und `agent.repo_dir` dürfen nicht derselbe Pfad sein.
+
+## Vollständige Konfigurationsvorlage
+
+Diese Vorlage zeigt jeden unterstützten installationsbezogenen Schlüssel. Sie ist eine Formreferenz, kein kopierbarer Standard. Entferne Abschnitte, die du nicht verwendest, entferne leere Listeneinträge und verwende entweder Inline-Werte oder `_file`-Werte für jedes secret-artige Feld.
+
+```yaml {filename="config.yaml"}
+controller:
+ listen_addr: ":7001"
+ repo_dir: "/data/repo-controller"
+ state_dir: "/data/state-controller"
+ log_dir: "/data/logs"
+
+ access_tokens:
+ - name: "web"
+ token: "REPLACE_WITH_WEB_ACCESS_TOKEN"
+ token_file: ""
+ enabled: true
+ comment: "Web-UI-Zugriffstoken"
+
+ nodes:
+ - id: "main"
+ display_name: "Main"
+ enabled: true
+ public_ipv4: ""
+ public_ipv6: ""
+ token: "REPLACE_WITH_MAIN_AGENT_TOKEN"
+ token_file: ""
+
+ git:
+ remote_url: ""
+ branch: "main"
+ pull_interval: ""
+ author_name: "Composia"
+ author_email: "composia@example.com"
+ auth:
+ username: ""
+ token: ""
+ token_file: ""
+
+ backup:
+ default_schedule: ""
+
+ updates:
+ default_check_schedule: ""
+ auto_apply: false
+ backup_before_update: true
+ digest_pin: false
+ semver:
+ default_allow:
+ - patch
+ - minor
+ forge_auth:
+ github:
+ url: "https://github.com"
+ token: ""
+ token_file: ""
+ api_url: "https://api.github.com"
+ gitlab:
+ url: "https://gitlab.com"
+ token: ""
+ token_file: ""
+ api_url: "https://gitlab.com/api/v4"
+ forgejo:
+ url: "https://forgejo.example.com"
+ token: ""
+ token_file: ""
+ api_url: ""
+
+ auto_deploy:
+ infra: false
+ services: false
+
+ dns:
+ cloudflare:
+ api_token: ""
+ api_token_file: ""
+ zones: []
+ alidns:
+ access_key_id: ""
+ access_key_id_file: ""
+ access_key_secret: ""
+ access_key_secret_file: ""
+ security_token: ""
+ security_token_file: ""
+ region_id: ""
+ zones: []
+ dnspod:
+ secret_id: ""
+ secret_id_file: ""
+ secret_key: ""
+ secret_key_file: ""
+ session_token: ""
+ session_token_file: ""
+ region: ""
+ zones: []
+ route53:
+ access_key_id: ""
+ access_key_id_file: ""
+ secret_access_key: ""
+ secret_access_key_file: ""
+ session_token: ""
+ session_token_file: ""
+ region: ""
+ profile: ""
+ hosted_zone_id: ""
+ zones: []
+ huaweicloud:
+ access_key_id: ""
+ access_key_id_file: ""
+ secret_access_key: ""
+ secret_access_key_file: ""
+ region_id: ""
+ zones: []
+
+ rustic:
+ main_nodes:
+ - "main"
+ maintenance:
+ forget_schedule: ""
+ prune_schedule: ""
+
+ secrets:
+ provider: age
+ identity_file: "/app/configs/age-identity.key"
+ recipient_file: ""
+ armor: true
+
+ notifications:
+ alertmanager:
+ enabled: true
+ listen_path: "/api/v1/alerts"
+ smtp:
+ enabled: false
+ host: ""
+ port: 587
+ encryption: starttls
+ username: ""
+ password: ""
+ password_file: ""
+ from: ""
+ to: []
+ on: []
+ task_sources: []
+ telegram:
+ enabled: false
+ bot_token: ""
+ bot_token_file: ""
+ chat_id: ""
+ on: []
+ task_sources: []
+
+agent:
+ controller_addr: "http://controller:7001"
+ controller_grpc: false
+ controller_headers:
+ - name: ""
+ value: ""
+ value_file: ""
+ node_id: "main"
+ token: "REPLACE_WITH_MAIN_AGENT_TOKEN"
+ token_file: ""
+ repo_dir: "/data/repo-agent"
+ state_dir: "/data/state-agent"
+ caddy:
+ generated_dir: ""
+```
+
+Behalte keine leeren Listeneinträge wie `controller_headers` mit einem leeren `name`. Sie werden nur zur Dokumentation der unterstützten Objektform gezeigt.
+
+Das Web-Zugriffstoken und das Haupt-Agent-Token müssen unterschiedlich sein.
+
+## Age-Schlüssel-Einrichtung
+
+`controller.secrets` ist optional. Konfiguriere es nur, wenn du Composia-verwaltete verschlüsselte Secrets verwendest.
+
+Wenn `controller.secrets` konfiguriert ist, ist `identity_file` erforderlich. `recipient_file` ist optional. Wenn es weggelassen wird, leitet Composia den Empfänger vom privaten Schlüssel ab.
+
+Generiere einen privaten Schlüssel:
+
+```bash
+age-keygen -o age-identity.key
+```
+
+Optionale Empfängerdatei:
+
+```bash
+age-keygen -y age-identity.key > age-recipients.txt
+```
+
+Verwende den privaten Schlüssel in der Konfiguration:
+
+```yaml
+secrets:
+ provider: age
+ identity_file: "/app/configs/age-identity.key"
+```
+
+Oder verwende beide Dateien:
+
+```yaml
+secrets:
+ provider: age
+ identity_file: "/app/configs/age-identity.key"
+ recipient_file: "/app/configs/age-recipients.txt"
+```
+
+`armor` ist optional und standardmäßig `true`.
+
+## Controller-Konfigurationsreferenz
+
+### Erforderliche Schlüssel
+
+| Schlüssel | Typ | Beschreibung |
+|-----|------|-------------|
+| `listen_addr` | `string` | Controller-Listening-Adresse, zum Beispiel `":7001"` oder `"127.0.0.1:7001"`. |
+| `repo_dir` | `string` | Pfad des Sollzustand-Git-Repositories. |
+| `state_dir` | `string` | Controller-Zustandspfad. |
+| `log_dir` | `string` | Aufgabenprotokoll-Verzeichnis. |
+| `nodes` | `[]object` | Konfigurierte Agent-Nodes. Der Schlüssel muss vorhanden sein, auch wenn leer. |
+
+### Optionale Schlüssel der obersten Ebene
+
+| Schlüssel | Typ | Beschreibung |
+|-----|------|-------------|
+| `access_tokens` | `[]object` | API-Tokens für Web-UI, CLI und externe Clients. |
+| `backup` | `object` | Globale Backup-Standardwerte. |
+| `git` | `object` | Remote-Synchronisation des Sollzustand-Repositories. |
+| `notifications` | `object` | Alertmanager-, SMTP- und Telegram-Benachrichtigungen. |
+| `dns` | `object` | DNS-Provider-Anmeldeinformationen. |
+| `rustic` | `object` | Rustic-Wartungseinstellungen. |
+| `secrets` | `object` | Age-Verschlüsselungseinstellungen. |
+| `updates` | `object` | Image-Update-Standardwerte und Forge-API-Auth. |
+| `auto_deploy` | `object` | Globale Auto-Deploy-Umschalter. |
+
+### `nodes[]`
+
+| Schlüssel | Typ | Erforderlich | Beschreibung |
+|-----|------|----------|-------------|
+| `id` | `string` | Ja | Eindeutige Node-ID. |
+| `display_name` | `string` | Nein | In der UI angezeigter Name. |
+| `enabled` | `bool` | Nein | Deaktiviert einen Node, ohne ihn zu entfernen. |
+| `public_ipv4` | `string` | Nein | Öffentliche IPv4, die von DNS-Workflows verwendet wird. |
+| `public_ipv6` | `string` | Nein | Öffentliche IPv6, die von DNS-Workflows verwendet wird. |
+| `token` | `string` | Ja* | Agent-Auth-Token. |
+| `token_file` | `string` | Nein | Liest das Token aus einer Datei. |
+
+*Verwende entweder `token` oder `token_file`, nicht beides.
+
+### `access_tokens[]`
+
+| Schlüssel | Typ | Erforderlich | Beschreibung |
+|-----|------|----------|-------------|
+| `name` | `string` | Ja | Token-Name. |
+| `token` | `string` | Ja* | Token-Wert. |
+| `token_file` | `string` | Nein | Liest das Token aus einer Datei. |
+| `enabled` | `bool` | Nein | Deaktiviert ein Token, ohne es zu entfernen. |
+| `comment` | `string` | Nein | Administrativer Hinweis. |
+
+Zugriffstokens dürfen Node-Tokens oder andere Zugriffstokens nicht duplizieren.
+
+### `git`
+
+| Schlüssel | Typ | Erforderlich | Beschreibung |
+|-----|------|----------|-------------|
+| `remote_url` | `string` | Nein | Git-Remote-URL. |
+| `branch` | `string` | Nein | Zu synchronisierender Branch. |
+| `pull_interval` | `string` | Bed. | Erforderlich, wenn `remote_url` gesetzt ist. |
+| `author_name` | `string` | Nein | Commit-Autor-Name für Controller-Schreibvorgänge. |
+| `author_email` | `string` | Nein | Commit-Autor-E-Mail. |
+| `auth.username` | `string` | Nein | Git-Benutzername. |
+| `auth.token` | `string` | Nein | Git-Token. |
+| `auth.token_file` | `string` | Nein | Liest Git-Token aus einer Datei. |
+
+### `secrets`
+
+Dieser gesamte Abschnitt ist optional. Wenn der Abschnitt vorhanden ist, gelten diese Regeln:
+
+| Schlüssel | Typ | Erforderlich | Beschreibung |
+|-----|------|----------|-------------|
+| `provider` | `string` | Ja | Muss `age` sein. |
+| `identity_file` | `string` | Ja | Pfad zum privaten Age-Schlüssel. |
+| `recipient_file` | `string` | Nein | Pfad zur Age-Empfängerdatei. Wenn weggelassen, wird der Empfänger von `identity_file` abgeleitet. |
+| `armor` | `bool` | Nein | ASCII-Armor-verschlüsselte Ausgabe. Standardmäßig `true`. |
+
+### `backup`
+
+| Schlüssel | Typ | Beschreibung |
+|-----|------|-------------|
+| `default_schedule` | `string` | Standard-Cron-Zeitplan für Dienst-Backups. |
+
+### `updates`
+
+| Schlüssel | Typ | Beschreibung |
+|-----|------|-------------|
+| `default_check_schedule` | `string` | Standard-Cron-Zeitplan für Image-Update-Prüfungen. |
+| `auto_apply` | `bool` | Wendet Updates standardmäßig automatisch an. |
+| `backup_before_update` | `bool` | Sichert Daten vor dem Anwenden von Updates. |
+| `digest_pin` | `bool` | Fixiert Images per Digest. |
+| `semver.default_allow` | `[]string` | Erlaubte Semver-Sprungstufen: `patch`, `minor`, `major`. |
+| `forge_auth.github` | `object` oder `[]object` | GitHub-API-Auth. |
+| `forge_auth.gitlab` | `object` oder `[]object` | GitLab-API-Auth. |
+| `forge_auth.forgejo` | `object` oder `[]object` | Forgejo-API-Auth. |
+
+Jeder Forge-Auth-Eintrag unterstützt:
+
+| Schlüssel | Typ | Beschreibung |
+|-----|------|-------------|
+| `url` | `string` | Forge-Basis-URL. |
+| `token` | `string` | API-Token. |
+| `token_file` | `string` | Liest API-Token aus einer Datei. |
+| `api_url` | `string` | API-URL-Override. |
+
+### `auto_deploy`
+
+| Schlüssel | Typ | Beschreibung |
+|-----|------|-------------|
+| `infra` | `bool` | Infrastrukturdienste nach Git-Änderungen automatisch deployen. |
+| `services` | `bool` | Reguläre Dienste nach Git-Änderungen automatisch deployen. |
+
+### `dns`
+
+| Provider-Schlüssel | Anmeldeschlüssel | Gemeinsame Schlüssel |
+|--------------|-----------------|-------------|
+| `cloudflare` | `api_token`, `api_token_file` | `zones` |
+| `alidns` | `access_key_id`, `access_key_id_file`, `access_key_secret`, `access_key_secret_file`, `security_token`, `security_token_file`, `region_id` | `zones` |
+| `dnspod` | `secret_id`, `secret_id_file`, `secret_key`, `secret_key_file`, `session_token`, `session_token_file`, `region` | `zones` |
+| `route53` | `access_key_id`, `access_key_id_file`, `secret_access_key`, `secret_access_key_file`, `session_token`, `session_token_file`, `region`, `profile`, `hosted_zone_id` | `zones` |
+| `huaweicloud` | `access_key_id`, `access_key_id_file`, `secret_access_key`, `secret_access_key_file`, `region_id` | `zones` |
+
+### `rustic`
+
+| Schlüssel | Typ | Beschreibung |
+|-----|------|-------------|
+| `main_nodes` | `[]string` | Node-IDs, die Rustic-Operationen ausführen. Jede muss auf `controller.nodes` verweisen. |
+| `maintenance.forget_schedule` | `string` | Cron-Zeitplan für `rustic forget`. |
+| `maintenance.prune_schedule` | `string` | Cron-Zeitplan für `rustic prune`. |
+
+### `notifications.alertmanager`
+
+| Schlüssel | Typ | Beschreibung |
+|-----|------|-------------|
+| `enabled` | `bool` | Standardmäßig aktiviert, wenn der Abschnitt existiert. |
+| `listen_path` | `string` | Webhook-Pfad. Standardmäßig `/api/v1/alerts`. Muss mit `/` beginnen. |
+
+### `notifications.smtp`
+
+| Schlüssel | Typ | Erforderlich wenn aktiviert | Beschreibung |
+|-----|------|-----------------------|-------------|
+| `enabled` | `bool` | Nein | Standardmäßig aktiviert, wenn der Abschnitt existiert. |
+| `host` | `string` | Ja | SMTP-Host. |
+| `port` | `int` | Ja | SMTP-Port, 1 bis 65535. |
+| `encryption` | `string` | Nein | `none`, `starttls` oder `ssl_tls`. Standardmäßig `starttls`. |
+| `username` | `string` | Nein | SMTP-Benutzername. |
+| `password` | `string` | Nein | SMTP-Passwort. |
+| `password_file` | `string` | Nein | Liest Passwort aus einer Datei. |
+| `from` | `string` | Ja | Absenderadresse. |
+| `to` | `[]string` | Ja | Empfängerliste. |
+| `on` | `[]string` | Nein | Benachrichtigungsereignisfilter. |
+| `task_sources` | `[]string` | Nein | Aufgabenquellenfilter: `web`, `cli`, `others`, `schedule`, `system`. |
+
+### `notifications.telegram`
+
+| Schlüssel | Typ | Erforderlich wenn aktiviert | Beschreibung |
+|-----|------|-----------------------|-------------|
+| `enabled` | `bool` | Nein | Standardmäßig aktiviert, wenn der Abschnitt existiert. |
+| `bot_token` | `string` | Ja* | Telegram-Bot-Token. |
+| `bot_token_file` | `string` | Nein | Liest Bot-Token aus einer Datei. |
+| `chat_id` | `string` | Ja | Ziel-Chat-ID. |
+| `on` | `[]string` | Nein | Benachrichtigungsereignisfilter. |
+| `task_sources` | `[]string` | Nein | Aufgabenquellenfilter. |
+
+## Agent-Konfigurationsreferenz
+
+| Schlüssel | Typ | Erforderlich | Beschreibung |
+|-----|------|----------|-------------|
+| `controller_addr` | `string` | Ja | Vom Agenten aus erreichbare Controller-URL. |
+| `controller_grpc` | `bool` | Nein | Verwendet gRPC anstelle von Connect über HTTP. |
+| `controller_headers` | `[]object` | Nein | Zusätzliche HTTP-Header, die an den Controller gesendet werden. |
+| `node_id` | `string` | Ja | Node-ID dieses Agenten. Muss mit `controller.nodes[].id` übereinstimmen. |
+| `token` | `string` | Ja* | Node-Token, das mit der Controller-Konfiguration übereinstimmt. |
+| `token_file` | `string` | Nein | Liest Node-Token aus einer Datei. |
+| `repo_dir` | `string` | Ja | Agent-Dienst-Repository-Pfad. |
+| `state_dir` | `string` | Ja | Agent-Zustandsverzeichnis. |
+| `caddy` | `object` | Nein | Agent-seitige Caddy-Einstellungen. |
+
+*Verwende entweder `token` oder `token_file`, nicht beides.
+
+### `controller_headers[]`
+
+| Schlüssel | Typ | Erforderlich | Beschreibung |
+|-----|------|----------|-------------|
+| `name` | `string` | Ja | HTTP-Header-Name. Header-Namen werden case-insensitiv dedupliziert. |
+| `value` | `string` | Ja* | Header-Wert. |
+| `value_file` | `string` | Nein | Liest Header-Wert aus einer Datei. |
+
+### `caddy`
+
+| Schlüssel | Typ | Beschreibung |
+|-----|------|-------------|
+| `generated_dir` | `string` | Generiertes Caddy-Konfigurationsverzeichnis. Standardmäßig `/caddy/generated`. |
+
+## Web-Umgebungsvariablen
+
+Der Webserver liest Umgebungsvariablen. In Docker Compose werden diese über `.env` gesetzt.
+
+| Variable | Erforderlich | Beschreibung |
+|----------|----------|-------------|
+| `WEB_CONTROLLER_ADDR` | Ja | Controller-Adresse aus Sicht des Webserver-Prozesses. In Docker Compose: `http://controller:7001`. |
+| `WEB_BROWSER_CONTROLLER_ADDR` | Ja | Controller-Adresse aus Sicht des Browsers. |
+| `WEB_CONTROLLER_ACCESS_TOKEN` | Ja | Controller-Zugriffstoken. Muss mit `controller.access_tokens[].token` übereinstimmen. |
+| `WEB_CONTROLLER_HEADERS` | Nein | JSON-Objekt mit zusätzlichen Headern, die der Webserver beim Aufruf des Controllers sendet. |
+| `WEB_LOGIN_USERNAME` | Ja | Web-Login-Benutzername. |
+| `WEB_LOGIN_PASSWORD_HASH` | Ja | Argon2-Passwort-Hash. |
+| `WEB_SESSION_SECRET` | Ja | Zufälliges Sitzungs-Signierungsgeheimnis. |
+| `ORIGIN` | Deployment-abhängig | Öffentlicher Ursprung des Webservers. |
+| `HOST` | Nein | Host-Bind-Adresse. |
+| `PORT` | Nein | Webserver-Port. |
+
+## Inline-Werte und `_file`-Werte
+
+Viele secret-artige Felder unterstützen sowohl Inline-Werte als auch Dateireferenzen. Beispiele:
+
+- `token` / `token_file`
+- `password` / `password_file`
+- `api_token` / `api_token_file`
+- `value` / `value_file`
+
+Verwende nur eine Form. Wenn beide gesetzt sind, schlägt der Start fehl.
diff --git a/site/content/docs/installation/configuration.fr.md b/site/content/docs/installation/configuration.fr.md
new file mode 100644
index 0000000..e0f079b
--- /dev/null
+++ b/site/content/docs/installation/configuration.fr.md
@@ -0,0 +1,457 @@
+---
+title: "Configuration"
+date: '2026-05-26T00:00:00+08:00'
+weight: 40
+---
+
+Cette page couvre la configuration au niveau de l'installation : configuration du contrôleur, configuration de l'agent, variables d'environnement web et configuration des clés age.
+
+Les définitions de service résident dans `composia-meta.yaml`. Voir le [Guide des services](/docs/guide/service/) pour ce fichier.
+
+## Structure du fichier de configuration
+
+Le contrôleur et l'agent utilisent le même format de fichier YAML. Un fichier peut contenir l'une ou l'autre section, ou les deux :
+
+```yaml
+controller:
+ # paramètres du contrôleur
+
+agent:
+ # paramètres de l'agent
+```
+
+Au moins l'un de `controller` ou `agent` doit être présent.
+
+Lorsque le même fichier de configuration contient les deux sections, l'agent local est traité comme le nœud intégré :
+
+- `agent.node_id` doit être `main`.
+- `controller.nodes` doit inclure une entrée avec `id: main`.
+- `controller.repo_dir` et `agent.repo_dir` ne doivent pas être le même chemin.
+
+## Modèle de configuration complet
+
+Ce modèle montre chaque clé prise en charge au niveau de l'installation. C'est une référence de structure, pas un défaut à copier-coller. Supprimez les sections que vous n'utilisez pas, supprimez les éléments de liste vides et utilisez soit des valeurs en ligne, soit des valeurs `_file` pour chaque champ de type secret.
+
+```yaml {filename="config.yaml"}
+controller:
+ listen_addr: ":7001"
+ repo_dir: "/data/repo-controller"
+ state_dir: "/data/state-controller"
+ log_dir: "/data/logs"
+
+ access_tokens:
+ - name: "web"
+ token: "REPLACE_WITH_WEB_ACCESS_TOKEN"
+ token_file: ""
+ enabled: true
+ comment: "Web UI access token"
+
+ nodes:
+ - id: "main"
+ display_name: "Main"
+ enabled: true
+ public_ipv4: ""
+ public_ipv6: ""
+ token: "REPLACE_WITH_MAIN_AGENT_TOKEN"
+ token_file: ""
+
+ git:
+ remote_url: ""
+ branch: "main"
+ pull_interval: ""
+ author_name: "Composia"
+ author_email: "composia@example.com"
+ auth:
+ username: ""
+ token: ""
+ token_file: ""
+
+ backup:
+ default_schedule: ""
+
+ updates:
+ default_check_schedule: ""
+ auto_apply: false
+ backup_before_update: true
+ digest_pin: false
+ semver:
+ default_allow:
+ - patch
+ - minor
+ forge_auth:
+ github:
+ url: "https://github.com"
+ token: ""
+ token_file: ""
+ api_url: "https://api.github.com"
+ gitlab:
+ url: "https://gitlab.com"
+ token: ""
+ token_file: ""
+ api_url: "https://gitlab.com/api/v4"
+ forgejo:
+ url: "https://forgejo.example.com"
+ token: ""
+ token_file: ""
+ api_url: ""
+
+ auto_deploy:
+ infra: false
+ services: false
+
+ dns:
+ cloudflare:
+ api_token: ""
+ api_token_file: ""
+ zones: []
+ alidns:
+ access_key_id: ""
+ access_key_id_file: ""
+ access_key_secret: ""
+ access_key_secret_file: ""
+ security_token: ""
+ security_token_file: ""
+ region_id: ""
+ zones: []
+ dnspod:
+ secret_id: ""
+ secret_id_file: ""
+ secret_key: ""
+ secret_key_file: ""
+ session_token: ""
+ session_token_file: ""
+ region: ""
+ zones: []
+ route53:
+ access_key_id: ""
+ access_key_id_file: ""
+ secret_access_key: ""
+ secret_access_key_file: ""
+ session_token: ""
+ session_token_file: ""
+ region: ""
+ profile: ""
+ hosted_zone_id: ""
+ zones: []
+ huaweicloud:
+ access_key_id: ""
+ access_key_id_file: ""
+ secret_access_key: ""
+ secret_access_key_file: ""
+ region_id: ""
+ zones: []
+
+ rustic:
+ main_nodes:
+ - "main"
+ maintenance:
+ forget_schedule: ""
+ prune_schedule: ""
+
+ secrets:
+ provider: age
+ identity_file: "/app/configs/age-identity.key"
+ recipient_file: ""
+ armor: true
+
+ notifications:
+ alertmanager:
+ enabled: true
+ listen_path: "/api/v1/alerts"
+ smtp:
+ enabled: false
+ host: ""
+ port: 587
+ encryption: starttls
+ username: ""
+ password: ""
+ password_file: ""
+ from: ""
+ to: []
+ on: []
+ task_sources: []
+ telegram:
+ enabled: false
+ bot_token: ""
+ bot_token_file: ""
+ chat_id: ""
+ on: []
+ task_sources: []
+
+agent:
+ controller_addr: "http://controller:7001"
+ controller_grpc: false
+ controller_headers:
+ - name: ""
+ value: ""
+ value_file: ""
+ node_id: "main"
+ token: "REPLACE_WITH_MAIN_AGENT_TOKEN"
+ token_file: ""
+ repo_dir: "/data/repo-agent"
+ state_dir: "/data/state-agent"
+ caddy:
+ generated_dir: ""
+```
+
+Ne conservez pas les éléments de liste vides comme `controller_headers` avec un `name` vide. Ils sont affichés uniquement pour documenter la structure d'objet prise en charge.
+
+Le jeton d'accès web et le jeton d'agent principal doivent être différents.
+
+## Configuration des clés age
+
+`controller.secrets` est optionnel. Configurez-le uniquement si vous utilisez les secrets chiffrés gérés par Composia.
+
+Lorsque `controller.secrets` est configuré, `identity_file` est requis. `recipient_file` est optionnel. S'il est omis, Composia dérive le destinataire de la clé privée.
+
+Générez une clé privée :
+
+```bash
+age-keygen -o age-identity.key
+```
+
+Fichier de destinataires optionnel :
+
+```bash
+age-keygen -y age-identity.key > age-recipients.txt
+```
+
+Utilisez la clé privée dans la configuration :
+
+```yaml
+secrets:
+ provider: age
+ identity_file: "/app/configs/age-identity.key"
+```
+
+Ou utilisez les deux fichiers :
+
+```yaml
+secrets:
+ provider: age
+ identity_file: "/app/configs/age-identity.key"
+ recipient_file: "/app/configs/age-recipients.txt"
+```
+
+`armor` est optionnel et vaut `true` par défaut.
+
+## Référence de configuration du contrôleur
+
+### Clés requises
+
+| Clé | Type | Description |
+|-----|------|-------------|
+| `listen_addr` | `string` | Adresse d'écoute du contrôleur, par exemple `":7001"` ou `"127.0.0.1:7001"`. |
+| `repo_dir` | `string` | Chemin du dépôt Git d'état désiré. |
+| `state_dir` | `string` | Chemin d'état du contrôleur. |
+| `log_dir` | `string` | Répertoire des journaux de tâches. |
+| `nodes` | `[]object` | Nœuds d'agent configurés. La clé doit être présente, même si vide. |
+
+### Clés optionnelles de niveau supérieur
+
+| Clé | Type | Description |
+|-----|------|-------------|
+| `access_tokens` | `[]object` | Jetons API pour l'interface web, la CLI et les clients externes. |
+| `backup` | `object` | Valeurs par défaut globales de sauvegarde. |
+| `git` | `object` | Synchronisation distante du dépôt d'état désiré. |
+| `notifications` | `object` | Notifications Alertmanager, SMTP et Telegram. |
+| `dns` | `object` | Identifiants des fournisseurs DNS. |
+| `rustic` | `object` | Paramètres de maintenance Rustic. |
+| `secrets` | `object` | Paramètres de chiffrement age. |
+| `updates` | `object` | Valeurs par défaut de mise à jour d'images et authentification des API forges. |
+| `auto_deploy` | `object` | Bascule globales de déploiement automatique. |
+
+### `nodes[]`
+
+| Clé | Type | Requis | Description |
+|-----|------|----------|-------------|
+| `id` | `string` | Oui | ID unique du nœud. |
+| `display_name` | `string` | Non | Nom affiché dans l'interface. |
+| `enabled` | `bool` | Non | Désactiver un nœud sans le supprimer. |
+| `public_ipv4` | `string` | Non | IPv4 publique utilisée par les workflows DNS. |
+| `public_ipv6` | `string` | Non | IPv6 publique utilisée par les workflows DNS. |
+| `token` | `string` | Oui* | Jeton d'authentification de l'agent. |
+| `token_file` | `string` | Non | Lire le jeton depuis un fichier. |
+
+*Utilisez soit `token`, soit `token_file`, pas les deux.
+
+### `access_tokens[]`
+
+| Clé | Type | Requis | Description |
+|-----|------|----------|-------------|
+| `name` | `string` | Oui | Nom du jeton. |
+| `token` | `string` | Oui* | Valeur du jeton. |
+| `token_file` | `string` | Non | Lire le jeton depuis un fichier. |
+| `enabled` | `bool` | Non | Désactiver un jeton sans le supprimer. |
+| `comment` | `string` | Non | Note administrative. |
+
+Les jetons d'accès ne doivent pas dupliquer les jetons de nœud ou d'autres jetons d'accès.
+
+### `git`
+
+| Clé | Type | Requis | Description |
+|-----|------|----------|-------------|
+| `remote_url` | `string` | Non | URL du dépôt Git distant. |
+| `branch` | `string` | Non | Branche à synchroniser. |
+| `pull_interval` | `string` | Cond. | Requis lorsque `remote_url` est défini. |
+| `author_name` | `string` | Non | Nom de l'auteur des commits pour les écritures du contrôleur. |
+| `author_email` | `string` | Non | E-mail de l'auteur des commits. |
+| `auth.username` | `string` | Non | Nom d'utilisateur Git. |
+| `auth.token` | `string` | Non | Jeton Git. |
+| `auth.token_file` | `string` | Non | Lire le jeton Git depuis un fichier. |
+
+### `secrets`
+
+Cette section entière est optionnelle. Si la section est présente, ces règles s'appliquent :
+
+| Clé | Type | Requis | Description |
+|-----|------|----------|-------------|
+| `provider` | `string` | Oui | Doit être `age`. |
+| `identity_file` | `string` | Oui | Chemin de la clé privée age. |
+| `recipient_file` | `string` | Non | Chemin du fichier de destinataires age. Si omis, le destinataire est dérivé de `identity_file`. |
+| `armor` | `bool` | Non | Sortie chiffrée en armure ASCII. Par défaut `true`. |
+
+### `backup`
+
+| Clé | Type | Description |
+|-----|------|-------------|
+| `default_schedule` | `string` | Planification cron par défaut pour les sauvegardes de service. |
+
+### `updates`
+
+| Clé | Type | Description |
+|-----|------|-------------|
+| `default_check_schedule` | `string` | Planification cron par défaut pour les vérifications de mise à jour d'images. |
+| `auto_apply` | `bool` | Appliquer les mises à jour automatiquement par défaut. |
+| `backup_before_update` | `bool` | Sauvegarder les données avant d'appliquer les mises à jour. |
+| `digest_pin` | `bool` | Épingler les images par empreinte. |
+| `semver.default_allow` | `[]string` | Niveaux d'incrément semver autorisés : `patch`, `minor`, `major`. |
+| `forge_auth.github` | `object` ou `[]object` | Authentification API GitHub. |
+| `forge_auth.gitlab` | `object` ou `[]object` | Authentification API GitLab. |
+| `forge_auth.forgejo` | `object` ou `[]object` | Authentification API Forgejo. |
+
+Chaque entrée d'authentification forge prend en charge :
+
+| Clé | Type | Description |
+|-----|------|-------------|
+| `url` | `string` | URL de base de la forge. |
+| `token` | `string` | Jeton API. |
+| `token_file` | `string` | Lire le jeton API depuis un fichier. |
+| `api_url` | `string` | Remplacement de l'URL de l'API. |
+
+### `auto_deploy`
+
+| Clé | Type | Description |
+|-----|------|-------------|
+| `infra` | `bool` | Déployer automatiquement les services d'infrastructure après des modifications Git. |
+| `services` | `bool` | Déployer automatiquement les services ordinaires après des modifications Git. |
+
+### `dns`
+
+| Clé fournisseur | Clés d'identifiants | Clés communes |
+|--------------|-----------------|-------------|
+| `cloudflare` | `api_token`, `api_token_file` | `zones` |
+| `alidns` | `access_key_id`, `access_key_id_file`, `access_key_secret`, `access_key_secret_file`, `security_token`, `security_token_file`, `region_id` | `zones` |
+| `dnspod` | `secret_id`, `secret_id_file`, `secret_key`, `secret_key_file`, `session_token`, `session_token_file`, `region` | `zones` |
+| `route53` | `access_key_id`, `access_key_id_file`, `secret_access_key`, `secret_access_key_file`, `session_token`, `session_token_file`, `region`, `profile`, `hosted_zone_id` | `zones` |
+| `huaweicloud` | `access_key_id`, `access_key_id_file`, `secret_access_key`, `secret_access_key_file`, `region_id` | `zones` |
+
+### `rustic`
+
+| Clé | Type | Description |
+|-----|------|-------------|
+| `main_nodes` | `[]string` | IDs des nœuds qui exécutent les opérations Rustic. Chacun doit référencer `controller.nodes`. |
+| `maintenance.forget_schedule` | `string` | Planification cron pour `rustic forget`. |
+| `maintenance.prune_schedule` | `string` | Planification cron pour `rustic prune`. |
+
+### `notifications.alertmanager`
+
+| Clé | Type | Description |
+|-----|------|-------------|
+| `enabled` | `bool` | Activé par défaut lorsque la section existe. |
+| `listen_path` | `string` | Chemin du webhook. Par défaut `/api/v1/alerts`. Doit commencer par `/`. |
+
+### `notifications.smtp`
+
+| Clé | Type | Requis si activé | Description |
+|-----|------|-----------------------|-------------|
+| `enabled` | `bool` | Non | Activé par défaut lorsque la section existe. |
+| `host` | `string` | Oui | Hôte SMTP. |
+| `port` | `int` | Oui | Port SMTP, de 1 à 65535. |
+| `encryption` | `string` | Non | `none`, `starttls` ou `ssl_tls`. Par défaut `starttls`. |
+| `username` | `string` | Non | Nom d'utilisateur SMTP. |
+| `password` | `string` | Non | Mot de passe SMTP. |
+| `password_file` | `string` | Non | Lire le mot de passe depuis un fichier. |
+| `from` | `string` | Oui | Adresse de l'expéditeur. |
+| `to` | `[]string` | Oui | Liste des destinataires. |
+| `on` | `[]string` | Non | Filtres d'événements de notification. |
+| `task_sources` | `[]string` | Non | Filtres de source de tâche : `web`, `cli`, `others`, `schedule`, `system`. |
+
+### `notifications.telegram`
+
+| Clé | Type | Requis si activé | Description |
+|-----|------|-----------------------|-------------|
+| `enabled` | `bool` | Non | Activé par défaut lorsque la section existe. |
+| `bot_token` | `string` | Oui* | Jeton du bot Telegram. |
+| `bot_token_file` | `string` | Non | Lire le jeton du bot depuis un fichier. |
+| `chat_id` | `string` | Oui | ID de la discussion cible. |
+| `on` | `[]string` | Non | Filtres d'événements de notification. |
+| `task_sources` | `[]string` | Non | Filtres de source de tâche. |
+
+## Référence de configuration de l'agent
+
+| Clé | Type | Requis | Description |
+|-----|------|----------|-------------|
+| `controller_addr` | `string` | Oui | URL du contrôleur accessible depuis l'agent. |
+| `controller_grpc` | `bool` | Non | Utiliser gRPC au lieu de Connect sur HTTP. |
+| `controller_headers` | `[]object` | Non | En-têtes HTTP supplémentaires envoyés au contrôleur. |
+| `node_id` | `string` | Oui | ID de nœud de cet agent. Doit correspondre à `controller.nodes[].id`. |
+| `token` | `string` | Oui* | Jeton de nœud correspondant à la configuration du contrôleur. |
+| `token_file` | `string` | Non | Lire le jeton de nœud depuis un fichier. |
+| `repo_dir` | `string` | Oui | Chemin du dépôt de services de l'agent. |
+| `state_dir` | `string` | Oui | Répertoire d'état de l'agent. |
+| `caddy` | `object` | Non | Paramètres Caddy côté agent. |
+
+*Utilisez soit `token`, soit `token_file`, pas les deux.
+
+### `controller_headers[]`
+
+| Clé | Type | Requis | Description |
+|-----|------|----------|-------------|
+| `name` | `string` | Oui | Nom de l'en-tête HTTP. Les noms d'en-tête sont dédupliqués sans tenir compte de la casse. |
+| `value` | `string` | Oui* | Valeur de l'en-tête. |
+| `value_file` | `string` | Non | Lire la valeur de l'en-tête depuis un fichier. |
+
+### `caddy`
+
+| Clé | Type | Description |
+|-----|------|-------------|
+| `generated_dir` | `string` | Répertoire de configuration Caddy généré. Par défaut `/caddy/generated`. |
+
+## Variables d'environnement web
+
+Le serveur web lit les variables d'environnement. Dans Docker Compose, celles-ci sont définies via `.env`.
+
+| Variable | Requise | Description |
+|----------|----------|-------------|
+| `WEB_CONTROLLER_ADDR` | Oui | Adresse du contrôleur depuis le processus du serveur web. Dans Docker Compose : `http://controller:7001`. |
+| `WEB_BROWSER_CONTROLLER_ADDR` | Oui | Adresse du contrôleur depuis le navigateur. |
+| `WEB_CONTROLLER_ACCESS_TOKEN` | Oui | Jeton d'accès au contrôleur. Doit correspondre à `controller.access_tokens[].token`. |
+| `WEB_CONTROLLER_HEADERS` | Non | Objet JSON d'en-têtes supplémentaires envoyés par le serveur web lors des appels au contrôleur. |
+| `WEB_LOGIN_USERNAME` | Oui | Nom d'utilisateur de connexion web. |
+| `WEB_LOGIN_PASSWORD_HASH` | Oui | Hachage de mot de passe Argon2. |
+| `WEB_SESSION_SECRET` | Oui | Secret aléatoire de signature de session. |
+| `ORIGIN` | Dépend du déploiement | Origine publique du serveur web. |
+| `HOST` | Non | Adresse de liaison de l'hôte. |
+| `PORT` | Non | Port du serveur web. |
+
+## Valeurs en ligne et valeurs `_file`
+
+De nombreux champs de type secret prennent en charge à la fois les valeurs en ligne et les références de fichiers. Exemples :
+
+- `token` / `token_file`
+- `password` / `password_file`
+- `api_token` / `api_token_file`
+- `value` / `value_file`
+
+Utilisez une seule forme. Si les deux sont définies, le démarrage échoue.
diff --git a/site/content/docs/installation/configuration.ja.md b/site/content/docs/installation/configuration.ja.md
new file mode 100644
index 0000000..77c6087
--- /dev/null
+++ b/site/content/docs/installation/configuration.ja.md
@@ -0,0 +1,457 @@
+---
+title: "設定"
+date: '2026-05-26T00:00:00+08:00'
+weight: 40
+---
+
+このページではインストールレベルの設定（コントローラー設定、エージェント設定、Web 環境変数、age 鍵のセットアップ）を説明します。
+
+サービス定義は `composia-meta.yaml` に記述します。このファイルについては [サービスガイド](/docs/guide/service/) を参照してください。
+
+## 設定ファイルの形式
+
+コントローラーとエージェントは同じ YAML ファイル形式を使用します。ファイルにはどちらかのセクション、または両方を含めることができます:
+
+```yaml
+controller:
+ # コントローラー設定
+
+agent:
+ # エージェント設定
+```
+
+`controller` または `agent` の少なくとも 1 つが存在する必要があります。
+
+同じ設定ファイルに両方のセクションが含まれる場合、ローカルエージェントは組み込みノードとして扱われます:
+
+- `agent.node_id` は `main` である必要があります。
+- `controller.nodes` には `id: main` のエントリが含まれている必要があります。
+- `controller.repo_dir` と `agent.repo_dir` は同じパスであってはいけません。
+
+## 完全な設定テンプレート
+
+このテンプレートはサポートされているすべてのインストールレベルのキーを示しています。形のリファレンスであり、コピー＆ペースト用のデフォルトではありません。使用しないセクションは削除し、空のリスト項目は削除し、各シークレット系フィールドにはインライン値または `_file` 値のいずれかを使用してください。
+
+```yaml {filename="config.yaml"}
+controller:
+ listen_addr: ":7001"
+ repo_dir: "/data/repo-controller"
+ state_dir: "/data/state-controller"
+ log_dir: "/data/logs"
+
+ access_tokens:
+ - name: "web"
+ token: "REPLACE_WITH_WEB_ACCESS_TOKEN"
+ token_file: ""
+ enabled: true
+ comment: "Web UI アクセストークン"
+
+ nodes:
+ - id: "main"
+ display_name: "Main"
+ enabled: true
+ public_ipv4: ""
+ public_ipv6: ""
+ token: "REPLACE_WITH_MAIN_AGENT_TOKEN"
+ token_file: ""
+
+ git:
+ remote_url: ""
+ branch: "main"
+ pull_interval: ""
+ author_name: "Composia"
+ author_email: "composia@example.com"
+ auth:
+ username: ""
+ token: ""
+ token_file: ""
+
+ backup:
+ default_schedule: ""
+
+ updates:
+ default_check_schedule: ""
+ auto_apply: false
+ backup_before_update: true
+ digest_pin: false
+ semver:
+ default_allow:
+ - patch
+ - minor
+ forge_auth:
+ github:
+ url: "https://github.com"
+ token: ""
+ token_file: ""
+ api_url: "https://api.github.com"
+ gitlab:
+ url: "https://gitlab.com"
+ token: ""
+ token_file: ""
+ api_url: "https://gitlab.com/api/v4"
+ forgejo:
+ url: "https://forgejo.example.com"
+ token: ""
+ token_file: ""
+ api_url: ""
+
+ auto_deploy:
+ infra: false
+ services: false
+
+ dns:
+ cloudflare:
+ api_token: ""
+ api_token_file: ""
+ zones: []
+ alidns:
+ access_key_id: ""
+ access_key_id_file: ""
+ access_key_secret: ""
+ access_key_secret_file: ""
+ security_token: ""
+ security_token_file: ""
+ region_id: ""
+ zones: []
+ dnspod:
+ secret_id: ""
+ secret_id_file: ""
+ secret_key: ""
+ secret_key_file: ""
+ session_token: ""
+ session_token_file: ""
+ region: ""
+ zones: []
+ route53:
+ access_key_id: ""
+ access_key_id_file: ""
+ secret_access_key: ""
+ secret_access_key_file: ""
+ session_token: ""
+ session_token_file: ""
+ region: ""
+ profile: ""
+ hosted_zone_id: ""
+ zones: []
+ huaweicloud:
+ access_key_id: ""
+ access_key_id_file: ""
+ secret_access_key: ""
+ secret_access_key_file: ""
+ region_id: ""
+ zones: []
+
+ rustic:
+ main_nodes:
+ - "main"
+ maintenance:
+ forget_schedule: ""
+ prune_schedule: ""
+
+ secrets:
+ provider: age
+ identity_file: "/app/configs/age-identity.key"
+ recipient_file: ""
+ armor: true
+
+ notifications:
+ alertmanager:
+ enabled: true
+ listen_path: "/api/v1/alerts"
+ smtp:
+ enabled: false
+ host: ""
+ port: 587
+ encryption: starttls
+ username: ""
+ password: ""
+ password_file: ""
+ from: ""
+ to: []
+ on: []
+ task_sources: []
+ telegram:
+ enabled: false
+ bot_token: ""
+ bot_token_file: ""
+ chat_id: ""
+ on: []
+ task_sources: []
+
+agent:
+ controller_addr: "http://controller:7001"
+ controller_grpc: false
+ controller_headers:
+ - name: ""
+ value: ""
+ value_file: ""
+ node_id: "main"
+ token: "REPLACE_WITH_MAIN_AGENT_TOKEN"
+ token_file: ""
+ repo_dir: "/data/repo-agent"
+ state_dir: "/data/state-agent"
+ caddy:
+ generated_dir: ""
+```
+
+空の `name` を持つ `controller_headers` のような空のリスト項目は保持しないでください。これらはサポートされているオブジェクトの形を文書化するためにのみ表示されています。
+
+Web アクセストークンとメインエージェントトークンは異なるものである必要があります。
+
+## age 鍵のセットアップ
+
+`controller.secrets` はオプションです。Composia 管理の暗号化シークレットを使用する場合にのみ設定してください。
+
+`controller.secrets` が設定されている場合、`identity_file` は必須です。`recipient_file` はオプションです。省略した場合、Composia は秘密鍵から受信者を導出します。
+
+秘密鍵の生成:
+
+```bash
+age-keygen -o age-identity.key
+```
+
+オプションの受信者ファイル:
+
+```bash
+age-keygen -y age-identity.key > age-recipients.txt
+```
+
+設定で秘密鍵を使用:
+
+```yaml
+secrets:
+ provider: age
+ identity_file: "/app/configs/age-identity.key"
+```
+
+または両方のファイルを使用:
+
+```yaml
+secrets:
+ provider: age
+ identity_file: "/app/configs/age-identity.key"
+ recipient_file: "/app/configs/age-recipients.txt"
+```
+
+`armor` はオプションで、デフォルトは `true` です。
+
+## コントローラー設定リファレンス
+
+### 必須キー
+
+| キー | 型 | 説明 |
+|-----|------|-------------|
+| `listen_addr` | `string` | コントローラーのリッスンアドレス。例: `":7001"` または `"127.0.0.1:7001"`。 |
+| `repo_dir` | `string` | 期待状態 Git リポジトリのパス。 |
+| `state_dir` | `string` | コントローラー状態のパス。 |
+| `log_dir` | `string` | タスクログディレクトリ。 |
+| `nodes` | `[]object` | 設定されたエージェントノード。空でもキーが存在する必要があります。 |
+
+### オプションのトップレベルキー
+
+| キー | 型 | 説明 |
+|-----|------|-------------|
+| `access_tokens` | `[]object` | Web UI、CLI、外部クライアント用の API トークン。 |
+| `backup` | `object` | グローバルバックアップデフォルト。 |
+| `git` | `object` | 期待状態リポジトリのリモート同期。 |
+| `notifications` | `object` | Alertmanager、SMTP、Telegram 通知。 |
+| `dns` | `object` | DNS プロバイダー認証情報。 |
+| `rustic` | `object` | Rustic メンテナンス設定。 |
+| `secrets` | `object` | Age 暗号化設定。 |
+| `updates` | `object` | イメージ更新デフォルトと forge API 認証。 |
+| `auto_deploy` | `object` | グローバル自動デプロイトグル。 |
+
+### `nodes[]`
+
+| キー | 型 | 必須 | 説明 |
+|-----|------|----------|-------------|
+| `id` | `string` | はい | 一意のノード ID。 |
+| `display_name` | `string` | いいえ | UI に表示される名前。 |
+| `enabled` | `bool` | いいえ | 削除せずにノードを無効化します。 |
+| `public_ipv4` | `string` | いいえ | DNS ワークフローで使用されるパブリック IPv4。 |
+| `public_ipv6` | `string` | いいえ | DNS ワークフローで使用されるパブリック IPv6。 |
+| `token` | `string` | はい* | エージェント認証トークン。 |
+| `token_file` | `string` | いいえ | ファイルからトークンを読み取ります。 |
+
+*`token` または `token_file` のいずれかを使用し、両方は使用しないでください。
+
+### `access_tokens[]`
+
+| キー | 型 | 必須 | 説明 |
+|-----|------|----------|-------------|
+| `name` | `string` | はい | トークン名。 |
+| `token` | `string` | はい* | トークン値。 |
+| `token_file` | `string` | いいえ | ファイルからトークンを読み取ります。 |
+| `enabled` | `bool` | いいえ | 削除せずにトークンを無効化します。 |
+| `comment` | `string` | いいえ | 管理用メモ。 |
+
+アクセストークンはノードトークンや他のアクセストークンと重複してはいけません。
+
+### `git`
+
+| キー | 型 | 必須 | 説明 |
+|-----|------|----------|-------------|
+| `remote_url` | `string` | いいえ | Git リモート URL。 |
+| `branch` | `string` | いいえ | 同期するブランチ。 |
+| `pull_interval` | `string` | 条件付き | `remote_url` が設定されている場合に必須。 |
+| `author_name` | `string` | いいえ | コントローラー書き込みのコミット作成者名。 |
+| `author_email` | `string` | いいえ | コミット作成者メール。 |
+| `auth.username` | `string` | いいえ | Git ユーザー名。 |
+| `auth.token` | `string` | いいえ | Git トークン。 |
+| `auth.token_file` | `string` | いいえ | ファイルから Git トークンを読み取ります。 |
+
+### `secrets`
+
+このセクション全体はオプションです。セクションが存在する場合、以下のルールが適用されます:
+
+| キー | 型 | 必須 | 説明 |
+|-----|------|----------|-------------|
+| `provider` | `string` | はい | `age` である必要があります。 |
+| `identity_file` | `string` | はい | Age 秘密鍵のパス。 |
+| `recipient_file` | `string` | いいえ | Age 受信者ファイルのパス。省略した場合、受信者は `identity_file` から導出されます。 |
+| `armor` | `bool` | いいえ | ASCII アーマー暗号化出力。デフォルトは `true`。 |
+
+### `backup`
+
+| キー | 型 | 説明 |
+|-----|------|-------------|
+| `default_schedule` | `string` | サービスバックアップのデフォルト cron スケジュール。 |
+
+### `updates`
+
+| キー | 型 | 説明 |
+|-----|------|-------------|
+| `default_check_schedule` | `string` | イメージ更新チェックのデフォルト cron スケジュール。 |
+| `auto_apply` | `bool` | デフォルトで更新を自動適用します。 |
+| `backup_before_update` | `bool` | 更新を適用する前にデータをバックアップします。 |
+| `digest_pin` | `bool` | イメージをダイジェストで固定します。 |
+| `semver.default_allow` | `[]string` | 許可される semver バンプレベル: `patch`、`minor`、`major`。 |
+| `forge_auth.github` | `object` または `[]object` | GitHub API 認証。 |
+| `forge_auth.gitlab` | `object` または `[]object` | GitLab API 認証。 |
+| `forge_auth.forgejo` | `object` または `[]object` | Forgejo API 認証。 |
+
+各 forge 認証エントリは以下をサポートします:
+
+| キー | 型 | 説明 |
+|-----|------|-------------|
+| `url` | `string` | Forge のベース URL。 |
+| `token` | `string` | API トークン。 |
+| `token_file` | `string` | ファイルから API トークンを読み取ります。 |
+| `api_url` | `string` | API URL の上書き。 |
+
+### `auto_deploy`
+
+| キー | 型 | 説明 |
+|-----|------|-------------|
+| `infra` | `bool` | Git 変更後にインフラストラクチャサービスを自動デプロイします。 |
+| `services` | `bool` | Git 変更後に通常のサービスを自動デプロイします。 |
+
+### `dns`
+
+| プロバイダーキー | 認証情報キー | 共通キー |
+|--------------|-----------------|-------------|
+| `cloudflare` | `api_token`, `api_token_file` | `zones` |
+| `alidns` | `access_key_id`, `access_key_id_file`, `access_key_secret`, `access_key_secret_file`, `security_token`, `security_token_file`, `region_id` | `zones` |
+| `dnspod` | `secret_id`, `secret_id_file`, `secret_key`, `secret_key_file`, `session_token`, `session_token_file`, `region` | `zones` |
+| `route53` | `access_key_id`, `access_key_id_file`, `secret_access_key`, `secret_access_key_file`, `session_token`, `session_token_file`, `region`, `profile`, `hosted_zone_id` | `zones` |
+| `huaweicloud` | `access_key_id`, `access_key_id_file`, `secret_access_key`, `secret_access_key_file`, `region_id` | `zones` |
+
+### `rustic`
+
+| キー | 型 | 説明 |
+|-----|------|-------------|
+| `main_nodes` | `[]string` | Rustic 操作を実行するノード ID。それぞれ `controller.nodes` を参照する必要があります。 |
+| `maintenance.forget_schedule` | `string` | `rustic forget` の cron スケジュール。 |
+| `maintenance.prune_schedule` | `string` | `rustic prune` の cron スケジュール。 |
+
+### `notifications.alertmanager`
+
+| キー | 型 | 説明 |
+|-----|------|-------------|
+| `enabled` | `bool` | セクションが存在する場合、デフォルトで有効。 |
+| `listen_path` | `string` | Webhook パス。デフォルトは `/api/v1/alerts`。`/` で始まる必要があります。 |
+
+### `notifications.smtp`
+
+| キー | 型 | 有効時に必須 | 説明 |
+|-----|------|-----------------------|-------------|
+| `enabled` | `bool` | いいえ | セクションが存在する場合、デフォルトで有効。 |
+| `host` | `string` | はい | SMTP ホスト。 |
+| `port` | `int` | はい | SMTP ポート（1 から 65535）。 |
+| `encryption` | `string` | いいえ | `none`、`starttls`、`ssl_tls`。デフォルトは `starttls`。 |
+| `username` | `string` | いいえ | SMTP ユーザー名。 |
+| `password` | `string` | いいえ | SMTP パスワード。 |
+| `password_file` | `string` | いいえ | ファイルからパスワードを読み取ります。 |
+| `from` | `string` | はい | 送信者アドレス。 |
+| `to` | `[]string` | はい | 受信者リスト。 |
+| `on` | `[]string` | いいえ | 通知イベントフィルター。 |
+| `task_sources` | `[]string` | いいえ | タスクソースフィルター: `web`、`cli`、`others`、`schedule`、`system`。 |
+
+### `notifications.telegram`
+
+| キー | 型 | 有効時に必須 | 説明 |
+|-----|------|-----------------------|-------------|
+| `enabled` | `bool` | いいえ | セクションが存在する場合、デフォルトで有効。 |
+| `bot_token` | `string` | はい* | Telegram ボットトークン。 |
+| `bot_token_file` | `string` | いいえ | ファイルからボットトークンを読み取ります。 |
+| `chat_id` | `string` | はい | ターゲットチャット ID。 |
+| `on` | `[]string` | いいえ | 通知イベントフィルター。 |
+| `task_sources` | `[]string` | いいえ | タスクソースフィルター。 |
+
+## エージェント設定リファレンス
+
+| キー | 型 | 必須 | 説明 |
+|-----|------|----------|-------------|
+| `controller_addr` | `string` | はい | エージェントから到達可能なコントローラー URL。 |
+| `controller_grpc` | `bool` | いいえ | HTTP 上の Connect の代わりに gRPC を使用します。 |
+| `controller_headers` | `[]object` | いいえ | コントローラーに送信される追加の HTTP ヘッダー。 |
+| `node_id` | `string` | はい | このエージェントのノード ID。`controller.nodes[].id` と一致する必要があります。 |
+| `token` | `string` | はい* | コントローラー設定と一致するノードトークン。 |
+| `token_file` | `string` | いいえ | ファイルからノードトークンを読み取ります。 |
+| `repo_dir` | `string` | はい | エージェントサービスリポジトリのパス。 |
+| `state_dir` | `string` | はい | エージェント状態ディレクトリ。 |
+| `caddy` | `object` | いいえ | エージェント側の Caddy 設定。 |
+
+*`token` または `token_file` のいずれかを使用し、両方は使用しないでください。
+
+### `controller_headers[]`
+
+| キー | 型 | 必須 | 説明 |
+|-----|------|----------|-------------|
+| `name` | `string` | はい | HTTP ヘッダー名。ヘッダー名は大文字小文字を区別せずに重複排除されます。 |
+| `value` | `string` | はい* | ヘッダー値。 |
+| `value_file` | `string` | いいえ | ファイルからヘッダー値を読み取ります。 |
+
+### `caddy`
+
+| キー | 型 | 説明 |
+|-----|------|-------------|
+| `generated_dir` | `string` | 生成された Caddy 設定ディレクトリ。デフォルトは `/caddy/generated`。 |
+
+## Web 環境変数
+
+Web サーバーは環境変数を読み取ります。Docker Compose ではこれらは `.env` を通じて設定されます。
+
+| 変数 | 必須 | 説明 |
+|----------|----------|-------------|
+| `WEB_CONTROLLER_ADDR` | はい | Web サーバープロセスからのコントローラーアドレス。Docker Compose では `http://controller:7001`。 |
+| `WEB_BROWSER_CONTROLLER_ADDR` | はい | ブラウザからのコントローラーアドレス。 |
+| `WEB_CONTROLLER_ACCESS_TOKEN` | はい | コントローラーアクセストークン。`controller.access_tokens[].token` と一致する必要があります。 |
+| `WEB_CONTROLLER_HEADERS` | いいえ | Web サーバーがコントローラーを呼び出す際に送信する追加ヘッダーの JSON オブジェクト。 |
+| `WEB_LOGIN_USERNAME` | はい | Web ログインユーザー名。 |
+| `WEB_LOGIN_PASSWORD_HASH` | はい | Argon2 パスワードハッシュ。 |
+| `WEB_SESSION_SECRET` | はい | ランダムなセッション署名シークレット。 |
+| `ORIGIN` | デプロイ依存 | Web サーバーの公開オリジン。 |
+| `HOST` | いいえ | ホストバインドアドレス。 |
+| `PORT` | いいえ | Web サーバーポート。 |
+
+## インライン値と `_file` 値
+
+多くのシークレット系フィールドはインライン値とファイル参照の両方をサポートしています。例:
+
+- `token` / `token_file`
+- `password` / `password_file`
+- `api_token` / `api_token_file`
+- `value` / `value_file`
+
+いずれか 1 つの形式のみを使用してください。両方が設定されている場合、起動に失敗します。
diff --git a/site/content/docs/installation/configuration.zh-hans.md b/site/content/docs/installation/configuration.zh-hans.md
new file mode 100644
index 0000000..1cdc896
--- /dev/null
+++ b/site/content/docs/installation/configuration.zh-hans.md
@@ -0,0 +1,457 @@
+---
+title: "配置"
+date: '2026-05-26T00:00:00+08:00'
+weight: 40
+---
+
+本页涵盖安装级别的配置：控制器配置、agent 配置、Web 环境变量和 age 密钥设置。
+
+服务定义位于 `composia-meta.yaml` 中。请参阅[服务指南](/docs/guide/service/)了解该文件。
+
+## 配置文件结构
+
+控制器和 agent 使用相同的 YAML 文件格式。一个文件可以包含其中一部分或两部分：
+
+```yaml
+controller:
+ # 控制器设置
+
+agent:
+ # agent 设置
+```
+
+`controller` 或 `agent` 中至少必须存在一个。
+
+当同一个配置文件包含两部分时，本地 agent 被视为内置节点：
+
+- `agent.node_id` 必须为 `main`。
+- `controller.nodes` 必须包含一个 `id: main` 的条目。
+- `controller.repo_dir` 和 `agent.repo_dir` 不能是同一路径。
+
+## 完整配置模板
+
+此模板展示了每个受支持的安装级别键。它是一个结构参考，而不是复制粘贴的默认配置。请删除您不使用的部分，删除空列表项，并对每个类似密钥的字段使用内联值或 `_file` 值。
+
+```yaml {filename="config.yaml"}
+controller:
+ listen_addr: ":7001"
+ repo_dir: "/data/repo-controller"
+ state_dir: "/data/state-controller"
+ log_dir: "/data/logs"
+
+ access_tokens:
+ - name: "web"
+ token: "REPLACE_WITH_WEB_ACCESS_TOKEN"
+ token_file: ""
+ enabled: true
+ comment: "Web UI access token"
+
+ nodes:
+ - id: "main"
+ display_name: "Main"
+ enabled: true
+ public_ipv4: ""
+ public_ipv6: ""
+ token: "REPLACE_WITH_MAIN_AGENT_TOKEN"
+ token_file: ""
+
+ git:
+ remote_url: ""
+ branch: "main"
+ pull_interval: ""
+ author_name: "Composia"
+ author_email: "composia@example.com"
+ auth:
+ username: ""
+ token: ""
+ token_file: ""
+
+ backup:
+ default_schedule: ""
+
+ updates:
+ default_check_schedule: ""
+ auto_apply: false
+ backup_before_update: true
+ digest_pin: false
+ semver:
+ default_allow:
+ - patch
+ - minor
+ forge_auth:
+ github:
+ url: "https://github.com"
+ token: ""
+ token_file: ""
+ api_url: "https://api.github.com"
+ gitlab:
+ url: "https://gitlab.com"
+ token: ""
+ token_file: ""
+ api_url: "https://gitlab.com/api/v4"
+ forgejo:
+ url: "https://forgejo.example.com"
+ token: ""
+ token_file: ""
+ api_url: ""
+
+ auto_deploy:
+ infra: false
+ services: false
+
+ dns:
+ cloudflare:
+ api_token: ""
+ api_token_file: ""
+ zones: []
+ alidns:
+ access_key_id: ""
+ access_key_id_file: ""
+ access_key_secret: ""
+ access_key_secret_file: ""
+ security_token: ""
+ security_token_file: ""
+ region_id: ""
+ zones: []
+ dnspod:
+ secret_id: ""
+ secret_id_file: ""
+ secret_key: ""
+ secret_key_file: ""
+ session_token: ""
+ session_token_file: ""
+ region: ""
+ zones: []
+ route53:
+ access_key_id: ""
+ access_key_id_file: ""
+ secret_access_key: ""
+ secret_access_key_file: ""
+ session_token: ""
+ session_token_file: ""
+ region: ""
+ profile: ""
+ hosted_zone_id: ""
+ zones: []
+ huaweicloud:
+ access_key_id: ""
+ access_key_id_file: ""
+ secret_access_key: ""
+ secret_access_key_file: ""
+ region_id: ""
+ zones: []
+
+ rustic:
+ main_nodes:
+ - "main"
+ maintenance:
+ forget_schedule: ""
+ prune_schedule: ""
+
+ secrets:
+ provider: age
+ identity_file: "/app/configs/age-identity.key"
+ recipient_file: ""
+ armor: true
+
+ notifications:
+ alertmanager:
+ enabled: true
+ listen_path: "/api/v1/alerts"
+ smtp:
+ enabled: false
+ host: ""
+ port: 587
+ encryption: starttls
+ username: ""
+ password: ""
+ password_file: ""
+ from: ""
+ to: []
+ on: []
+ task_sources: []
+ telegram:
+ enabled: false
+ bot_token: ""
+ bot_token_file: ""
+ chat_id: ""
+ on: []
+ task_sources: []
+
+agent:
+ controller_addr: "http://controller:7001"
+ controller_grpc: false
+ controller_headers:
+ - name: ""
+ value: ""
+ value_file: ""
+ node_id: "main"
+ token: "REPLACE_WITH_MAIN_AGENT_TOKEN"
+ token_file: ""
+ repo_dir: "/data/repo-agent"
+ state_dir: "/data/state-agent"
+ caddy:
+ generated_dir: ""
+```
+
+不要保留空的列表项，例如包含空 `name` 的 `controller_headers`。它们仅用于展示支持的对象结构。
+
+Web 访问令牌和主 agent 令牌必须不同。
+
+## Age 密钥设置
+
+`controller.secrets` 是可选的。仅当使用 Composia 管理的加密密钥时才配置它。
+
+当配置了 `controller.secrets` 时，`identity_file` 是必填的。`recipient_file` 是可选的。如果省略，Composia 从私钥派生接收者。
+
+生成私钥：
+
+```bash
+age-keygen -o age-identity.key
+```
+
+可选的接收者文件：
+
+```bash
+age-keygen -y age-identity.key > age-recipients.txt
+```
+
+在配置中使用私钥：
+
+```yaml
+secrets:
+ provider: age
+ identity_file: "/app/configs/age-identity.key"
+```
+
+或同时使用两个文件：
+
+```yaml
+secrets:
+ provider: age
+ identity_file: "/app/configs/age-identity.key"
+ recipient_file: "/app/configs/age-recipients.txt"
+```
+
+`armor` 是可选的，默认为 `true`。
+
+## 控制器配置参考
+
+### 必填键
+
+| 键 | 类型 | 描述 |
+|-----|------|-------------|
+| `listen_addr` | `string` | 控制器监听地址，例如 `":7001"` 或 `"127.0.0.1:7001"`。 |
+| `repo_dir` | `string` | 期望状态 Git 仓库路径。 |
+| `state_dir` | `string` | 控制器状态路径。 |
+| `log_dir` | `string` | 任务日志目录。 |
+| `nodes` | `[]object` | 已配置的 agent 节点。该键必须存在，即使为空。 |
+
+### 可选顶级键
+
+| 键 | 类型 | 描述 |
+|-----|------|-------------|
+| `access_tokens` | `[]object` | 用于 Web UI、CLI 和外部客户端的 API 令牌。 |
+| `backup` | `object` | 全局备份默认值。 |
+| `git` | `object` | 期望状态仓库的远程同步。 |
+| `notifications` | `object` | Alertmanager、SMTP 和 Telegram 通知。 |
+| `dns` | `object` | DNS 提供商凭据。 |
+| `rustic` | `object` | Rustic 维护设置。 |
+| `secrets` | `object` | Age 加密设置。 |
+| `updates` | `object` | 镜像更新默认值和 forge API 认证。 |
+| `auto_deploy` | `object` | 全局自动部署开关。 |
+
+### `nodes[]`
+
+| 键 | 类型 | 必填 | 描述 |
+|-----|------|----------|-------------|
+| `id` | `string` | 是 | 唯一的节点 ID。 |
+| `display_name` | `string` | 否 | UI 中显示的名称。 |
+| `enabled` | `bool` | 否 | 禁用节点而不删除配置。 |
+| `public_ipv4` | `string` | 否 | DNS 工作流使用的公网 IPv4。 |
+| `public_ipv6` | `string` | 否 | DNS 工作流使用的公网 IPv6。 |
+| `token` | `string` | 是* | Agent 认证令牌。 |
+| `token_file` | `string` | 否 | 从文件读取令牌。 |
+
+*使用 `token` 或 `token_file`，不能同时使用。
+
+### `access_tokens[]`
+
+| 键 | 类型 | 必填 | 描述 |
+|-----|------|----------|-------------|
+| `name` | `string` | 是 | 令牌名称。 |
+| `token` | `string` | 是* | 令牌值。 |
+| `token_file` | `string` | 否 | 从文件读取令牌。 |
+| `enabled` | `bool` | 否 | 禁用令牌而不删除配置。 |
+| `comment` | `string` | 否 | 管理备注。 |
+
+访问令牌不能与节点令牌或其他访问令牌重复。
+
+### `git`
+
+| 键 | 类型 | 必填 | 描述 |
+|-----|------|----------|-------------|
+| `remote_url` | `string` | 否 | Git 远程 URL。 |
+| `branch` | `string` | 否 | 要同步的分支。 |
+| `pull_interval` | `string` | 条件 | 当 `remote_url` 设置时必填。 |
+| `author_name` | `string` | 否 | 控制器写入的提交作者名。 |
+| `author_email` | `string` | 否 | 提交作者邮箱。 |
+| `auth.username` | `string` | 否 | Git 用户名。 |
+| `auth.token` | `string` | 否 | Git 令牌。 |
+| `auth.token_file` | `string` | 否 | 从文件读取 Git 令牌。 |
+
+### `secrets`
+
+整个部分是可选的。如果该部分存在，以下规则适用：
+
+| 键 | 类型 | 必填 | 描述 |
+|-----|------|----------|-------------|
+| `provider` | `string` | 是 | 必须为 `age`。 |
+| `identity_file` | `string` | 是 | Age 私钥路径。 |
+| `recipient_file` | `string` | 否 | Age 接收者文件路径。如果省略，接收者从 `identity_file` 派生。 |
+| `armor` | `bool` | 否 | ASCII 封装加密输出。默认为 `true`。 |
+
+### `backup`
+
+| 键 | 类型 | 描述 |
+|-----|------|-------------|
+| `default_schedule` | `string` | 服务备份的默认 cron 计划。 |
+
+### `updates`
+
+| 键 | 类型 | 描述 |
+|-----|------|-------------|
+| `default_check_schedule` | `string` | 镜像更新检查的默认 cron 计划。 |
+| `auto_apply` | `bool` | 默认自动应用更新。 |
+| `backup_before_update` | `bool` | 在应用更新前备份数据。 |
+| `digest_pin` | `bool` | 通过摘要锁定镜像。 |
+| `semver.default_allow` | `[]string` | 允许的 semver 升级级别：`patch`、`minor`、`major`。 |
+| `forge_auth.github` | `object` 或 `[]object` | GitHub API 认证。 |
+| `forge_auth.gitlab` | `object` 或 `[]object` | GitLab API 认证。 |
+| `forge_auth.forgejo` | `object` 或 `[]object` | Forgejo API 认证。 |
+
+每个 forge 认证条目支持：
+
+| 键 | 类型 | 描述 |
+|-----|------|-------------|
+| `url` | `string` | Forge 基础 URL。 |
+| `token` | `string` | API 令牌。 |
+| `token_file` | `string` | 从文件读取 API 令牌。 |
+| `api_url` | `string` | API URL 覆盖。 |
+
+### `auto_deploy`
+
+| 键 | 类型 | 描述 |
+|-----|------|-------------|
+| `infra` | `bool` | Git 更改后自动部署基础设施服务。 |
+| `services` | `bool` | Git 更改后自动部署普通服务。 |
+
+### `dns`
+
+| 提供商键 | 凭据键 | 通用键 |
+|--------------|-----------------|-------------|
+| `cloudflare` | `api_token`、`api_token_file` | `zones` |
+| `alidns` | `access_key_id`、`access_key_id_file`、`access_key_secret`、`access_key_secret_file`、`security_token`、`security_token_file`、`region_id` | `zones` |
+| `dnspod` | `secret_id`、`secret_id_file`、`secret_key`、`secret_key_file`、`session_token`、`session_token_file`、`region` | `zones` |
+| `route53` | `access_key_id`、`access_key_id_file`、`secret_access_key`、`secret_access_key_file`、`session_token`、`session_token_file`、`region`、`profile`、`hosted_zone_id` | `zones` |
+| `huaweicloud` | `access_key_id`、`access_key_id_file`、`secret_access_key`、`secret_access_key_file`、`region_id` | `zones` |
+
+### `rustic`
+
+| 键 | 类型 | 描述 |
+|-----|------|-------------|
+| `main_nodes` | `[]string` | 运行 Rustic 操作的节点 ID 列表。每个都必须引用 `controller.nodes`。 |
+| `maintenance.forget_schedule` | `string` | `rustic forget` 的 cron 计划。 |
+| `maintenance.prune_schedule` | `string` | `rustic prune` 的 cron 计划。 |
+
+### `notifications.alertmanager`
+
+| 键 | 类型 | 描述 |
+|-----|------|-------------|
+| `enabled` | `bool` | 当该部分存在时默认启用。 |
+| `listen_path` | `string` | Webhook 路径。默认为 `/api/v1/alerts`。必须以 `/` 开头。 |
+
+### `notifications.smtp`
+
+| 键 | 类型 | 启用时必填 | 描述 |
+|-----|------|-----------------------|-------------|
+| `enabled` | `bool` | 否 | 当该部分存在时默认启用。 |
+| `host` | `string` | 是 | SMTP 主机。 |
+| `port` | `int` | 是 | SMTP 端口，1 到 65535。 |
+| `encryption` | `string` | 否 | `none`、`starttls` 或 `ssl_tls`。默认为 `starttls`。 |
+| `username` | `string` | 否 | SMTP 用户名。 |
+| `password` | `string` | 否 | SMTP 密码。 |
+| `password_file` | `string` | 否 | 从文件读取密码。 |
+| `from` | `string` | 是 | 发件人地址。 |
+| `to` | `[]string` | 是 | 收件人列表。 |
+| `on` | `[]string` | 否 | 通知事件过滤器。 |
+| `task_sources` | `[]string` | 否 | 任务来源过滤器：`web`、`cli`、`others`、`schedule`、`system`。 |
+
+### `notifications.telegram`
+
+| 键 | 类型 | 启用时必填 | 描述 |
+|-----|------|-----------------------|-------------|
+| `enabled` | `bool` | 否 | 当该部分存在时默认启用。 |
+| `bot_token` | `string` | 是* | Telegram 机器人令牌。 |
+| `bot_token_file` | `string` | 否 | 从文件读取机器人令牌。 |
+| `chat_id` | `string` | 是 | 目标聊天 ID。 |
+| `on` | `[]string` | 否 | 通知事件过滤器。 |
+| `task_sources` | `[]string` | 否 | 任务来源过滤器。 |
+
+## Agent 配置参考
+
+| 键 | 类型 | 必填 | 描述 |
+|-----|------|----------|-------------|
+| `controller_addr` | `string` | 是 | Agent 可访问的控制器 URL。 |
+| `controller_grpc` | `bool` | 否 | 使用 gRPC 而非基于 HTTP 的 Connect。 |
+| `controller_headers` | `[]object` | 否 | 发送给控制器的额外 HTTP 头。 |
+| `node_id` | `string` | 是 | 此 agent 的节点 ID。必须与 `controller.nodes[].id` 匹配。 |
+| `token` | `string` | 是* | 与控制器配置匹配的节点令牌。 |
+| `token_file` | `string` | 否 | 从文件读取节点令牌。 |
+| `repo_dir` | `string` | 是 | Agent 服务仓库路径。 |
+| `state_dir` | `string` | 是 | Agent 状态目录。 |
+| `caddy` | `object` | 否 | Agent 端 Caddy 设置。 |
+
+*使用 `token` 或 `token_file`，不能同时使用。
+
+### `controller_headers[]`
+
+| 键 | 类型 | 必填 | 描述 |
+|-----|------|----------|-------------|
+| `name` | `string` | 是 | HTTP 头名称。头名称按不区分大小写去重。 |
+| `value` | `string` | 是* | 头值。 |
+| `value_file` | `string` | 否 | 从文件读取头值。 |
+
+### `caddy`
+
+| 键 | 类型 | 描述 |
+|-----|------|-------------|
+| `generated_dir` | `string` | 生成的 Caddy 配置目录。默认为 `/caddy/generated`。 |
+
+## Web 环境变量
+
+Web 服务器读取环境变量。在 Docker Compose 中，这些通过 `.env` 设置。
+
+| 变量 | 必填 | 描述 |
+|----------|----------|-------------|
+| `WEB_CONTROLLER_ADDR` | 是 | 从 Web 服务器进程访问的控制器地址。在 Docker Compose 中：`http://controller:7001`。 |
+| `WEB_BROWSER_CONTROLLER_ADDR` | 是 | 从浏览器访问的控制器地址。 |
+| `WEB_CONTROLLER_ACCESS_TOKEN` | 是 | 控制器访问令牌。必须与 `controller.access_tokens[].token` 匹配。 |
+| `WEB_CONTROLLER_HEADERS` | 否 | Web 服务器调用控制器时发送的额外 HTTP 头的 JSON 对象。 |
+| `WEB_LOGIN_USERNAME` | 是 | Web 登录用户名。 |
+| `WEB_LOGIN_PASSWORD_HASH` | 是 | Argon2 密码哈希。 |
+| `WEB_SESSION_SECRET` | 是 | 随机会话签名密钥。 |
+| `ORIGIN` | 视部署而定 | Web 服务器的公开来源。 |
+| `HOST` | 否 | 主机绑定地址。 |
+| `PORT` | 否 | Web 服务器端口。 |
+
+## 内联值与 `_file` 值
+
+许多类似密钥的字段同时支持内联值和文件引用。例如：
+
+- `token` / `token_file`
+- `password` / `password_file`
+- `api_token` / `api_token_file`
+- `value` / `value_file`
+
+只能使用一种形式。如果两者都设置，启动将失败。
diff --git a/site/content/docs/installation/configuration.zh-hant.md b/site/content/docs/installation/configuration.zh-hant.md
new file mode 100644
index 0000000..31d4428
--- /dev/null
+++ b/site/content/docs/installation/configuration.zh-hant.md
@@ -0,0 +1,457 @@
+---
+title: "設定"
+date: '2026-05-26T00:00:00+08:00'
+weight: 40
+---
+
+此頁面涵蓋安裝層級的設定：控制器設定、代理設定、Web 環境變數與 age 金鑰設定。
+
+服務定義位於 `composia-meta.yaml` 中。請參見[服務指南](/docs/guide/service/)了解該檔案。
+
+## 設定檔結構
+
+控制器和代理使用相同的 YAML 檔案格式。一個檔案可以包含任一區段或兩者：
+
+```yaml
+controller:
+ # 控制器設定
+
+agent:
+ # 代理設定
+```
+
+必須至少存在 `controller` 或 `agent` 其中之一。
+
+當同一個設定檔同時包含兩個區段時，本地代理被視為內建節點：
+
+- `agent.node_id` 必須為 `main`。
+- `controller.nodes` 必須包含一個帶有 `id: main` 的項目。
+- `controller.repo_dir` 和 `agent.repo_dir` 不得為相同路徑。
+
+## 完整設定範本
+
+此範本顯示每個支援的安裝層級鍵。它是結構參考，而非可直接複製貼上的預設值。移除您不使用的區段、移除空清單項目，並對每個類似密鑰的欄位使用內聯值或 `_file` 值。
+
+```yaml {filename="config.yaml"}
+controller:
+ listen_addr: ":7001"
+ repo_dir: "/data/repo-controller"
+ state_dir: "/data/state-controller"
+ log_dir: "/data/logs"
+
+ access_tokens:
+ - name: "web"
+ token: "REPLACE_WITH_WEB_ACCESS_TOKEN"
+ token_file: ""
+ enabled: true
+ comment: "Web UI 存取權杖"
+
+ nodes:
+ - id: "main"
+ display_name: "Main"
+ enabled: true
+ public_ipv4: ""
+ public_ipv6: ""
+ token: "REPLACE_WITH_MAIN_AGENT_TOKEN"
+ token_file: ""
+
+ git:
+ remote_url: ""
+ branch: "main"
+ pull_interval: ""
+ author_name: "Composia"
+ author_email: "composia@example.com"
+ auth:
+ username: ""
+ token: ""
+ token_file: ""
+
+ backup:
+ default_schedule: ""
+
+ updates:
+ default_check_schedule: ""
+ auto_apply: false
+ backup_before_update: true
+ digest_pin: false
+ semver:
+ default_allow:
+ - patch
+ - minor
+ forge_auth:
+ github:
+ url: "https://github.com"
+ token: ""
+ token_file: ""
+ api_url: "https://api.github.com"
+ gitlab:
+ url: "https://gitlab.com"
+ token: ""
+ token_file: ""
+ api_url: "https://gitlab.com/api/v4"
+ forgejo:
+ url: "https://forgejo.example.com"
+ token: ""
+ token_file: ""
+ api_url: ""
+
+ auto_deploy:
+ infra: false
+ services: false
+
+ dns:
+ cloudflare:
+ api_token: ""
+ api_token_file: ""
+ zones: []
+ alidns:
+ access_key_id: ""
+ access_key_id_file: ""
+ access_key_secret: ""
+ access_key_secret_file: ""
+ security_token: ""
+ security_token_file: ""
+ region_id: ""
+ zones: []
+ dnspod:
+ secret_id: ""
+ secret_id_file: ""
+ secret_key: ""
+ secret_key_file: ""
+ session_token: ""
+ session_token_file: ""
+ region: ""
+ zones: []
+ route53:
+ access_key_id: ""
+ access_key_id_file: ""
+ secret_access_key: ""
+ secret_access_key_file: ""
+ session_token: ""
+ session_token_file: ""
+ region: ""
+ profile: ""
+ hosted_zone_id: ""
+ zones: []
+ huaweicloud:
+ access_key_id: ""
+ access_key_id_file: ""
+ secret_access_key: ""
+ secret_access_key_file: ""
+ region_id: ""
+ zones: []
+
+ rustic:
+ main_nodes:
+ - "main"
+ maintenance:
+ forget_schedule: ""
+ prune_schedule: ""
+
+ secrets:
+ provider: age
+ identity_file: "/app/configs/age-identity.key"
+ recipient_file: ""
+ armor: true
+
+ notifications:
+ alertmanager:
+ enabled: true
+ listen_path: "/api/v1/alerts"
+ smtp:
+ enabled: false
+ host: ""
+ port: 587
+ encryption: starttls
+ username: ""
+ password: ""
+ password_file: ""
+ from: ""
+ to: []
+ on: []
+ task_sources: []
+ telegram:
+ enabled: false
+ bot_token: ""
+ bot_token_file: ""
+ chat_id: ""
+ on: []
+ task_sources: []
+
+agent:
+ controller_addr: "http://controller:7001"
+ controller_grpc: false
+ controller_headers:
+ - name: ""
+ value: ""
+ value_file: ""
+ node_id: "main"
+ token: "REPLACE_WITH_MAIN_AGENT_TOKEN"
+ token_file: ""
+ repo_dir: "/data/repo-agent"
+ state_dir: "/data/state-agent"
+ caddy:
+ generated_dir: ""
+```
+
+請勿保留如含有空白 `name` 的 `controller_headers` 等空清單項目。它們僅為記錄支援的物件結構而顯示。
+
+Web 存取權杖和主要代理權杖必須不同。
+
+## Age 金鑰設定
+
+`controller.secrets` 是可選的。僅在您使用 Composia 管理的加密密鑰時才設定它。
+
+當設定了 `controller.secrets` 時，`identity_file` 為必要項。`recipient_file` 為可選。若省略，Composia 從私鑰衍生接收者。
+
+產生私鑰：
+
+```bash
+age-keygen -o age-identity.key
+```
+
+可選的接收者檔案：
+
+```bash
+age-keygen -y age-identity.key > age-recipients.txt
+```
+
+在設定中使用私鑰：
+
+```yaml
+secrets:
+ provider: age
+ identity_file: "/app/configs/age-identity.key"
+```
+
+或同時使用兩個檔案：
+
+```yaml
+secrets:
+ provider: age
+ identity_file: "/app/configs/age-identity.key"
+ recipient_file: "/app/configs/age-recipients.txt"
+```
+
+`armor` 是可選的，預設為 `true`。
+
+## 控制器設定參考
+
+### 必要鍵
+
+| 鍵 | 型別 | 說明 |
+|-----|------|-------------|
+| `listen_addr` | `string` | 控制器監聽位址，例如 `":7001"` 或 `"127.0.0.1:7001"`。 |
+| `repo_dir` | `string` | 期望狀態 Git 存放庫路徑。 |
+| `state_dir` | `string` | 控制器狀態路徑。 |
+| `log_dir` | `string` | 任務日誌目錄。 |
+| `nodes` | `[]object` | 已設定的代理節點。此鍵必須存在，即使是空的。 |
+
+### 可選的頂層鍵
+
+| 鍵 | 型別 | 說明 |
+|-----|------|-------------|
+| `access_tokens` | `[]object` | 用於 Web UI、CLI 和外部客戶端的 API 權杖。 |
+| `backup` | `object` | 全域備份預設值。 |
+| `git` | `object` | 期望狀態存放庫遠端同步。 |
+| `notifications` | `object` | Alertmanager、SMTP 和 Telegram 通知。 |
+| `dns` | `object` | DNS 提供者憑證。 |
+| `rustic` | `object` | Rustic 維護設定。 |
+| `secrets` | `object` | Age 加密設定。 |
+| `updates` | `object` | 映像檔更新預設值和 forge API 驗證。 |
+| `auto_deploy` | `object` | 全域自動部署開關。 |
+
+### `nodes[]`
+
+| 鍵 | 型別 | 必要 | 說明 |
+|-----|------|----------|-------------|
+| `id` | `string` | 是 | 唯一的節點 ID。 |
+| `display_name` | `string` | 否 | UI 中顯示的名稱。 |
+| `enabled` | `bool` | 否 | 不移除節點而停用它。 |
+| `public_ipv4` | `string` | 否 | DNS 工作流程使用的公開 IPv4。 |
+| `public_ipv6` | `string` | 否 | DNS 工作流程使用的公開 IPv6。 |
+| `token` | `string` | 是* | 代理驗證權杖。 |
+| `token_file` | `string` | 否 | 從檔案讀取權杖。 |
+
+*使用 `token` 或 `token_file`，不能同時兩者。
+
+### `access_tokens[]`
+
+| 鍵 | 型別 | 必要 | 說明 |
+|-----|------|----------|-------------|
+| `name` | `string` | 是 | 權杖名稱。 |
+| `token` | `string` | 是* | 權杖值。 |
+| `token_file` | `string` | 否 | 從檔案讀取權杖。 |
+| `enabled` | `bool` | 否 | 不移除權杖而停用它。 |
+| `comment` | `string` | 否 | 管理備註。 |
+
+存取權杖不得與節點權杖或其他存取權杖重複。
+
+### `git`
+
+| 鍵 | 型別 | 必要 | 說明 |
+|-----|------|----------|-------------|
+| `remote_url` | `string` | 否 | Git 遠端 URL。 |
+| `branch` | `string` | 否 | 要同步的分支。 |
+| `pull_interval` | `string` | 條件必要 | 設定 `remote_url` 時為必要項。 |
+| `author_name` | `string` | 否 | 控制器寫入的提交作者名稱。 |
+| `author_email` | `string` | 否 | 提交作者電子郵件。 |
+| `auth.username` | `string` | 否 | Git 使用者名稱。 |
+| `auth.token` | `string` | 否 | Git 權杖。 |
+| `auth.token_file` | `string` | 否 | 從檔案讀取 Git 權杖。 |
+
+### `secrets`
+
+整個區段是可選的。若此區段存在，則以下規則適用：
+
+| 鍵 | 型別 | 必要 | 說明 |
+|-----|------|----------|-------------|
+| `provider` | `string` | 是 | 必須為 `age`。 |
+| `identity_file` | `string` | 是 | Age 私鑰路徑。 |
+| `recipient_file` | `string` | 否 | Age 接收者檔案路徑。若省略，從 `identity_file` 衍生接收者。 |
+| `armor` | `bool` | 否 | ASCII armoring 加密輸出。預設為 `true`。 |
+
+### `backup`
+
+| 鍵 | 型別 | 說明 |
+|-----|------|-------------|
+| `default_schedule` | `string` | 服務備份的預設 cron 排程。 |
+
+### `updates`
+
+| 鍵 | 型別 | 說明 |
+|-----|------|-------------|
+| `default_check_schedule` | `string` | 映像檔更新檢查的預設 cron 排程。 |
+| `auto_apply` | `bool` | 預設自動套用更新。 |
+| `backup_before_update` | `bool` | 套用更新前備份資料。 |
+| `digest_pin` | `bool` | 以摘要固定映像檔。 |
+| `semver.default_allow` | `[]string` | 允許的 semver 版本升級層級：`patch`、`minor`、`major`。 |
+| `forge_auth.github` | `object` 或 `[]object` | GitHub API 驗證。 |
+| `forge_auth.gitlab` | `object` 或 `[]object` | GitLab API 驗證。 |
+| `forge_auth.forgejo` | `object` 或 `[]object` | Forgejo API 驗證。 |
+
+每個 forge 驗證項目支援：
+
+| 鍵 | 型別 | 說明 |
+|-----|------|-------------|
+| `url` | `string` | Forge 基礎 URL。 |
+| `token` | `string` | API 權杖。 |
+| `token_file` | `string` | 從檔案讀取 API 權杖。 |
+| `api_url` | `string` | API URL 覆蓋。 |
+
+### `auto_deploy`
+
+| 鍵 | 型別 | 說明 |
+|-----|------|-------------|
+| `infra` | `bool` | Git 變更後自動部署基礎架構服務。 |
+| `services` | `bool` | Git 變更後自動部署一般服務。 |
+
+### `dns`
+
+| 提供者鍵 | 憑證鍵 | 共用鍵 |
+|--------------|-----------------|-------------|
+| `cloudflare` | `api_token`、`api_token_file` | `zones` |
+| `alidns` | `access_key_id`、`access_key_id_file`、`access_key_secret`、`access_key_secret_file`、`security_token`、`security_token_file`、`region_id` | `zones` |
+| `dnspod` | `secret_id`、`secret_id_file`、`secret_key`、`secret_key_file`、`session_token`、`session_token_file`、`region` | `zones` |
+| `route53` | `access_key_id`、`access_key_id_file`、`secret_access_key`、`secret_access_key_file`、`session_token`、`session_token_file`、`region`、`profile`、`hosted_zone_id` | `zones` |
+| `huaweicloud` | `access_key_id`、`access_key_id_file`、`secret_access_key`、`secret_access_key_file`、`region_id` | `zones` |
+
+### `rustic`
+
+| 鍵 | 型別 | 說明 |
+|-----|------|-------------|
+| `main_nodes` | `[]string` | 執行 Rustic 操作的節點 ID。每個必須引用 `controller.nodes`。 |
+| `maintenance.forget_schedule` | `string` | `rustic forget` 的 cron 排程。 |
+| `maintenance.prune_schedule` | `string` | `rustic prune` 的 cron 排程。 |
+
+### `notifications.alertmanager`
+
+| 鍵 | 型別 | 說明 |
+|-----|------|-------------|
+| `enabled` | `bool` | 當區段存在時預設啟用。 |
+| `listen_path` | `string` | Webhook 路徑。預設為 `/api/v1/alerts`。必須以 `/` 開頭。 |
+
+### `notifications.smtp`
+
+| 鍵 | 型別 | 啟用時必要 | 說明 |
+|-----|------|-----------------------|-------------|
+| `enabled` | `bool` | 否 | 當區段存在時預設啟用。 |
+| `host` | `string` | 是 | SMTP 主機。 |
+| `port` | `int` | 是 | SMTP 連接埠，1 到 65535。 |
+| `encryption` | `string` | 否 | `none`、`starttls` 或 `ssl_tls`。預設為 `starttls`。 |
+| `username` | `string` | 否 | SMTP 使用者名稱。 |
+| `password` | `string` | 否 | SMTP 密碼。 |
+| `password_file` | `string` | 否 | 從檔案讀取密碼。 |
+| `from` | `string` | 是 | 寄件者地址。 |
+| `to` | `[]string` | 是 | 收件者清單。 |
+| `on` | `[]string` | 否 | 通知事件過濾器。 |
+| `task_sources` | `[]string` | 否 | 任務來源過濾器：`web`、`cli`、`others`、`schedule`、`system`。 |
+
+### `notifications.telegram`
+
+| 鍵 | 型別 | 啟用時必要 | 說明 |
+|-----|------|-----------------------|-------------|
+| `enabled` | `bool` | 否 | 當區段存在時預設啟用。 |
+| `bot_token` | `string` | 是* | Telegram 機器人權杖。 |
+| `bot_token_file` | `string` | 否 | 從檔案讀取機器人權杖。 |
+| `chat_id` | `string` | 是 | 目標聊天室 ID。 |
+| `on` | `[]string` | 否 | 通知事件過濾器。 |
+| `task_sources` | `[]string` | 否 | 任務來源過濾器。 |
+
+## 代理設定參考
+
+| 鍵 | 型別 | 必要 | 說明 |
+|-----|------|----------|-------------|
+| `controller_addr` | `string` | 是 | 代理可連線的控制器 URL。 |
+| `controller_grpc` | `bool` | 否 | 使用 gRPC 而非基於 HTTP 的 Connect。 |
+| `controller_headers` | `[]object` | 否 | 發送給控制器的額外 HTTP 標頭。 |
+| `node_id` | `string` | 是 | 此代理的節點 ID。必須與 `controller.nodes[].id` 匹配。 |
+| `token` | `string` | 是* | 與控制器設定匹配的節點權杖。 |
+| `token_file` | `string` | 否 | 從檔案讀取節點權杖。 |
+| `repo_dir` | `string` | 是 | 代理服務存放庫路徑。 |
+| `state_dir` | `string` | 是 | 代理狀態目錄。 |
+| `caddy` | `object` | 否 | 代理端 Caddy 設定。 |
+
+*使用 `token` 或 `token_file`，不能同時兩者。
+
+### `controller_headers[]`
+
+| 鍵 | 型別 | 必要 | 說明 |
+|-----|------|----------|-------------|
+| `name` | `string` | 是 | HTTP 標頭名稱。標頭名稱以不區分大小寫的方式去重。 |
+| `value` | `string` | 是* | 標頭值。 |
+| `value_file` | `string` | 否 | 從檔案讀取標頭值。 |
+
+### `caddy`
+
+| 鍵 | 型別 | 說明 |
+|-----|------|-------------|
+| `generated_dir` | `string` | 產生的 Caddy 設定目錄。預設為 `/caddy/generated`。 |
+
+## Web 環境變數
+
+Web 伺服器讀取環境變數。在 Docker Compose 中，這些透過 `.env` 設定。
+
+| 變數 | 必要 | 說明 |
+|----------|----------|-------------|
+| `WEB_CONTROLLER_ADDR` | 是 | 從 Web 伺服器處理程序看到的控制器位址。在 Docker Compose 中：`http://controller:7001`。 |
+| `WEB_BROWSER_CONTROLLER_ADDR` | 是 | 從瀏覽器看到的控制器位址。 |
+| `WEB_CONTROLLER_ACCESS_TOKEN` | 是 | 控制器存取權杖。必須與 `controller.access_tokens[].token` 匹配。 |
+| `WEB_CONTROLLER_HEADERS` | 否 | Web 伺服器呼叫控制器時發送的額外標頭的 JSON 物件。 |
+| `WEB_LOGIN_USERNAME` | 是 | Web 登入使用者名稱。 |
+| `WEB_LOGIN_PASSWORD_HASH` | 是 | Argon2 密碼雜湊。 |
+| `WEB_SESSION_SECRET` | 是 | 隨機的會話簽名密鑰。 |
+| `ORIGIN` | 取決於部署 | Web 伺服器的公開來源。 |
+| `HOST` | 否 | 主機繫結位址。 |
+| `PORT` | 否 | Web 伺服器連接埠。 |
+
+## 內聯值與 `_file` 值
+
+許多類似密鑰的欄位同時支援內聯值和檔案引用。範例：
+
+- `token` / `token_file`
+- `password` / `password_file`
+- `api_token` / `api_token_file`
+- `value` / `value_file`
+
+僅使用一種形式。若同時設定兩者，啟動會失敗。
diff --git a/site/content/docs/installation/docker-compose.de.md b/site/content/docs/installation/docker-compose.de.md
new file mode 100644
index 0000000..cf3926b
--- /dev/null
+++ b/site/content/docs/installation/docker-compose.de.md
@@ -0,0 +1,120 @@
+---
+title: "Docker Compose"
+date: '2026-05-26T00:00:00+08:00'
+weight: 20
+---
+
+Der Docker-Compose-Stack führt den Controller, einen lokalen Agenten und die Web-UI aus der kanonischen [`docker-compose.yaml`](https://forgejo.alexma.top/alexma233/composia/src/branch/main/docker-compose.yaml) aus.
+
+## Dateien herunterladen
+
+Du musst nicht das gesamte Repository für eine Docker-Compose-Installation klonen. Lade die Compose-Datei und die Umgebungsvorlage herunter:
+
+```bash
+curl -LO https://forgejo.alexma.top/alexma233/composia/raw/branch/main/docker-compose.yaml
+curl -L https://forgejo.alexma.top/alexma233/composia/raw/branch/main/.env.example -o .env
+```
+
+Bearbeite `.env` vor dem Start des Stacks. Die Vorlage ist nach Rolle gruppiert; für den All-in-One-Stack behalte alle Gruppen. Siehe [Konfiguration](../configuration/) für die Bedeutung jeder Variable.
+
+Ermittle die Docker-Socket-Gruppen-ID auf dem Host:
+
+```bash
+stat -c '%g' /var/run/docker.sock
+```
+
+Setze `DOCKER_SOCK_GID` auf diesen Wert.
+
+## Agent-Repository-Pfad
+
+`COMPOSIA_AGENT_REPO_DIR` wird eingebunden als:
+
+```yaml
+- ${COMPOSIA_AGENT_REPO_DIR}:${COMPOSIA_AGENT_REPO_DIR}
+```
+
+Der Host-Pfad und der Container-Pfad müssen identisch sein. Der Agent ruft den Host-Docker-Daemon auf, und der Host-Docker-Daemon löst Bind-Mounts aus dem Host-Dateisystem auf. Wenn das Dienst-Repository unter einem anderen Pfad im Agent-Container eingebunden ist, kann Docker Compose Host-Pfade generieren, die nicht existieren.
+
+Verwende denselben absoluten Pfad auf beiden Seiten, zum Beispiel:
+
+```bash
+COMPOSIA_AGENT_REPO_DIR=/srv/composia/repo-agent
+```
+
+## Grundlegende `config.yaml`
+
+Erstelle `config.yaml` innerhalb von `COMPOSIA_CONFIG_DIR`. Die Docker-Compose-Datei bindet dieses Verzeichnis unter `/app/configs` ein.
+
+```yaml {filename="config.yaml"}
+controller:
+ listen_addr: ":7001"
+ repo_dir: "/data/repo-controller"
+ state_dir: "/data/state-controller"
+ log_dir: "/data/logs"
+ access_tokens:
+ - name: "web"
+ token: "REPLACE_WITH_WEB_ACCESS_TOKEN"
+ enabled: true
+ nodes:
+ - id: "main"
+ display_name: "Main"
+ enabled: true
+ token: "REPLACE_WITH_MAIN_AGENT_TOKEN"
+agent:
+ controller_addr: "http://controller:7001"
+ node_id: "main"
+ token: "REPLACE_WITH_MAIN_AGENT_TOKEN"
+ repo_dir: "/data/repo-agent"
+ state_dir: "/data/state-agent"
+```
+
+Setze `WEB_CONTROLLER_ACCESS_TOKEN` in `.env` auf denselben Wert wie `controller.access_tokens[0].token`.
+
+## Web-Passwort
+
+`WEB_LOGIN_PASSWORD_HASH` muss ein Argon2-Passwort-Hash sein. Verwende ein Argon2-fähiges Passwort-Hashing-Tool und füge den vollständigen kodierten Hash in `.env` ein.
+
+Generiere `WEB_SESSION_SECRET` mit einem beliebigen kryptografisch sicheren Zufallsgenerator, zum Beispiel:
+
+```bash
+openssl rand -hex 32
+```
+
+## Start
+
+```bash
+docker compose up -d
+docker compose ps
+```
+
+Öffne die Web-UI unter `http://localhost:3000`.
+
+## Rollenaufteilung
+
+Die Compose-Datei ist nach Rolle gegliedert:
+
+- **Controller-Stack**: `init-repo-controller`, `init-perms-controller`, `controller`.
+- **Web-UI**: `web`.
+- **Gemeinsame Initialisierung**: `init-config-perms`.
+- **Agent-Stack**: `init-perms-agent`, `agent`.
+
+Für alles, was über die All-in-One-Bereitstellung hinausgeht, trenne diese Abschnitte explizit für deine Topologie. Controller und Web können zusammen oder getrennt laufen. Jeder Agent-Node behält den Agent-Stack und seinen eigenen Docker-Socket-Zugriff.
+
+## Images
+
+Release-Images werden auf Forgejo, GHCR und Docker Hub veröffentlicht:
+
+| Komponente | Forgejo | GHCR | Docker Hub |
+|-----------|---------|------|------------|
+| CLI | `forgejo.alexma.top/alexma233/composia-cli` | `ghcr.io/alexma233/composia-cli` | `alexma233/composia-cli` |
+| Controller | `forgejo.alexma.top/alexma233/composia-controller` | `ghcr.io/alexma233/composia-controller` | `alexma233/composia-controller` |
+| Agent | `forgejo.alexma.top/alexma233/composia-agent` | `ghcr.io/alexma233/composia-agent` | `alexma233/composia-agent` |
+| Web | `forgejo.alexma.top/alexma233/composia-web` | `ghcr.io/alexma233/composia-web` | `alexma233/composia-web` |
+
+Canary-Images werden nur auf Forgejo und GHCR veröffentlicht.
+
+## Häufige Prüfungen
+
+- Controller kann nicht starten: Überprüfe, ob `config.yaml` unter `COMPOSIA_CONFIG_DIR` existiert und dass erforderliche Controller-Pfade vorhanden sind oder erstellt werden können.
+- Agent kann Docker nicht verwenden: Überprüfe, ob `DOCKER_SOCK_GID` mit `/var/run/docker.sock` auf dem Host übereinstimmt.
+- Web kann Controller nicht erreichen: `WEB_CONTROLLER_ADDR` ist für den Webserver-Container, während `WEB_BROWSER_CONTROLLER_ADDR` für den Browser ist.
diff --git a/site/content/docs/installation/docker-compose.fr.md b/site/content/docs/installation/docker-compose.fr.md
new file mode 100644
index 0000000..0e259d9
--- /dev/null
+++ b/site/content/docs/installation/docker-compose.fr.md
@@ -0,0 +1,120 @@
+---
+title: "Docker Compose"
+date: '2026-05-26T00:00:00+08:00'
+weight: 20
+---
+
+La pile Docker Compose exécute le contrôleur, un agent local et l'interface web à partir du fichier [`docker-compose.yaml`](https://forgejo.alexma.top/alexma233/composia/src/branch/main/docker-compose.yaml) canonique.
+
+## Télécharger les fichiers
+
+Vous n'avez pas besoin de cloner tout le dépôt pour une installation Docker Compose. Téléchargez le fichier Compose et le modèle d'environnement :
+
+```bash
+curl -LO https://forgejo.alexma.top/alexma233/composia/raw/branch/main/docker-compose.yaml
+curl -L https://forgejo.alexma.top/alexma233/composia/raw/branch/main/.env.example -o .env
+```
+
+Modifiez `.env` avant de démarrer la pile. Le modèle est groupé par rôle ; pour la pile tout-en-un, conservez tous les groupes. Voir [Configuration](../configuration/) pour la signification de chaque variable.
+
+Trouvez l'ID de groupe du socket Docker sur l'hôte :
+
+```bash
+stat -c '%g' /var/run/docker.sock
+```
+
+Définissez `DOCKER_SOCK_GID` à cette valeur.
+
+## Chemin du dépôt de l'agent
+
+`COMPOSIA_AGENT_REPO_DIR` est monté comme :
+
+```yaml
+- ${COMPOSIA_AGENT_REPO_DIR}:${COMPOSIA_AGENT_REPO_DIR}
+```
+
+Le chemin hôte et le chemin conteneur doivent être identiques. L'agent invoque le démon Docker de l'hôte, et le démon Docker de l'hôte résout les montages bind à partir du système de fichiers hôte. Si le dépôt de services est monté à un chemin différent à l'intérieur du conteneur de l'agent, Docker Compose peut générer des chemins hôte qui n'existent pas.
+
+Utilisez le même chemin absolu des deux côtés, par exemple :
+
+```bash
+COMPOSIA_AGENT_REPO_DIR=/srv/composia/repo-agent
+```
+
+## `config.yaml` de base
+
+Créez `config.yaml` dans `COMPOSIA_CONFIG_DIR`. Le fichier Docker Compose monte ce répertoire vers `/app/configs`.
+
+```yaml {filename="config.yaml"}
+controller:
+ listen_addr: ":7001"
+ repo_dir: "/data/repo-controller"
+ state_dir: "/data/state-controller"
+ log_dir: "/data/logs"
+ access_tokens:
+ - name: "web"
+ token: "REPLACE_WITH_WEB_ACCESS_TOKEN"
+ enabled: true
+ nodes:
+ - id: "main"
+ display_name: "Main"
+ enabled: true
+ token: "REPLACE_WITH_MAIN_AGENT_TOKEN"
+agent:
+ controller_addr: "http://controller:7001"
+ node_id: "main"
+ token: "REPLACE_WITH_MAIN_AGENT_TOKEN"
+ repo_dir: "/data/repo-agent"
+ state_dir: "/data/state-agent"
+```
+
+Définissez `WEB_CONTROLLER_ACCESS_TOKEN` dans `.env` à la même valeur que `controller.access_tokens[0].token`.
+
+## Mot de passe web
+
+`WEB_LOGIN_PASSWORD_HASH` doit être un hachage de mot de passe Argon2. Utilisez un outil de hachage de mot de passe compatible Argon2 et collez le hachage encodé complet dans `.env`.
+
+Générez `WEB_SESSION_SECRET` avec n'importe quel générateur aléatoire cryptographiquement sécurisé, par exemple :
+
+```bash
+openssl rand -hex 32
+```
+
+## Démarrage
+
+```bash
+docker compose up -d
+docker compose ps
+```
+
+Ouvrez l'interface web à `http://localhost:3000`.
+
+## Séparation des rôles
+
+Le fichier Compose est sectionné par rôle :
+
+- **Pile contrôleur** : `init-repo-controller`, `init-perms-controller`, `controller`.
+- **Interface web** : `web`.
+- **Initialisation partagée** : `init-config-perms`.
+- **Pile agent** : `init-perms-agent`, `agent`.
+
+Pour tout déploiement au-delà du tout-en-un, séparez explicitement ces sections pour votre topologie. Le contrôleur et le web peuvent s'exécuter ensemble ou séparément. Chaque nœud agent conserve la pile agent et son propre accès au socket Docker.
+
+## Images
+
+Les images de release sont publiées sur Forgejo, GHCR et Docker Hub :
+
+| Composant | Forgejo | GHCR | Docker Hub |
+|-----------|---------|------|------------|
+| CLI | `forgejo.alexma.top/alexma233/composia-cli` | `ghcr.io/alexma233/composia-cli` | `alexma233/composia-cli` |
+| Contrôleur | `forgejo.alexma.top/alexma233/composia-controller` | `ghcr.io/alexma233/composia-controller` | `alexma233/composia-controller` |
+| Agent | `forgejo.alexma.top/alexma233/composia-agent` | `ghcr.io/alexma233/composia-agent` | `alexma233/composia-agent` |
+| Web | `forgejo.alexma.top/alexma233/composia-web` | `ghcr.io/alexma233/composia-web` | `alexma233/composia-web` |
+
+Les images canary sont publiées uniquement sur Forgejo et GHCR.
+
+## Vérifications courantes
+
+- Le contrôleur ne peut pas démarrer : vérifiez que `config.yaml` existe dans `COMPOSIA_CONFIG_DIR` et que les chemins requis du contrôleur existent ou peuvent être créés.
+- L'agent ne peut pas utiliser Docker : vérifiez que `DOCKER_SOCK_GID` correspond à `/var/run/docker.sock` sur l'hôte.
+- Le web ne peut pas atteindre le contrôleur : `WEB_CONTROLLER_ADDR` est pour le conteneur du serveur web, tandis que `WEB_BROWSER_CONTROLLER_ADDR` est pour le navigateur.
diff --git a/site/content/docs/installation/docker-compose.ja.md b/site/content/docs/installation/docker-compose.ja.md
new file mode 100644
index 0000000..6b2a2cc
--- /dev/null
+++ b/site/content/docs/installation/docker-compose.ja.md
@@ -0,0 +1,120 @@
+---
+title: "Docker Compose"
+date: '2026-05-26T00:00:00+08:00'
+weight: 20
+---
+
+Docker Compose スタックは、公式の [`docker-compose.yaml`](https://forgejo.alexma.top/alexma233/composia/src/branch/main/docker-compose.yaml) からコントローラー、1 つのローカルエージェント、Web UI を実行します。
+
+## ファイルのダウンロード
+
+Docker Compose インストールのためにリポジトリ全体をクローンする必要はありません。Compose ファイルと環境テンプレートをダウンロードします:
+
+```bash
+curl -LO https://forgejo.alexma.top/alexma233/composia/raw/branch/main/docker-compose.yaml
+curl -L https://forgejo.alexma.top/alexma233/composia/raw/branch/main/.env.example -o .env
+```
+
+スタックを起動する前に `.env` を編集します。テンプレートはロールごとにグループ化されています。オールインワンスタックの場合はすべてのグループを保持します。各変数の意味については [設定](../configuration/) を参照してください。
+
+ホスト上の Docker ソケットグループ ID を確認します:
+
+```bash
+stat -c '%g' /var/run/docker.sock
+```
+
+`DOCKER_SOCK_GID` をその値に設定します。
+
+## エージェントリポジトリパス
+
+`COMPOSIA_AGENT_REPO_DIR` は次のようにマウントされます:
+
+```yaml
+- ${COMPOSIA_AGENT_REPO_DIR}:${COMPOSIA_AGENT_REPO_DIR}
+```
+
+ホストパスとコンテナパスは同じである必要があります。エージェントはホスト Docker デーモンを呼び出し、ホスト Docker デーモンはホストファイルシステムからバインドマウントを解決します。サービスリポジトリがエージェントコンテナ内で異なるパスにマウントされている場合、Docker Compose は存在しないホストパスを生成する可能性があります。
+
+両側で同じ絶対パスを使用してください。例:
+
+```bash
+COMPOSIA_AGENT_REPO_DIR=/srv/composia/repo-agent
+```
+
+## 基本的な `config.yaml`
+
+`COMPOSIA_CONFIG_DIR` 内に `config.yaml` を作成します。Docker Compose ファイルはこのディレクトリを `/app/configs` にマウントします。
+
+```yaml {filename="config.yaml"}
+controller:
+ listen_addr: ":7001"
+ repo_dir: "/data/repo-controller"
+ state_dir: "/data/state-controller"
+ log_dir: "/data/logs"
+ access_tokens:
+ - name: "web"
+ token: "REPLACE_WITH_WEB_ACCESS_TOKEN"
+ enabled: true
+ nodes:
+ - id: "main"
+ display_name: "Main"
+ enabled: true
+ token: "REPLACE_WITH_MAIN_AGENT_TOKEN"
+agent:
+ controller_addr: "http://controller:7001"
+ node_id: "main"
+ token: "REPLACE_WITH_MAIN_AGENT_TOKEN"
+ repo_dir: "/data/repo-agent"
+ state_dir: "/data/state-agent"
+```
+
+`.env` の `WEB_CONTROLLER_ACCESS_TOKEN` を `controller.access_tokens[0].token` と同じ値に設定します。
+
+## Web パスワード
+
+`WEB_LOGIN_PASSWORD_HASH` は Argon2 パスワードハッシュである必要があります。Argon2 対応のパスワードハッシュツールを使用し、完全なエンコード済みハッシュを `.env` に貼り付けます。
+
+`WEB_SESSION_SECRET` は暗号論的に安全な乱数生成器で生成します。例:
+
+```bash
+openssl rand -hex 32
+```
+
+## 起動
+
+```bash
+docker compose up -d
+docker compose ps
+```
+
+`http://localhost:3000` で Web UI を開きます。
+
+## ロール分割
+
+Compose ファイルはロールごとにセクション分けされています:
+
+- **コントローラースタック**: `init-repo-controller`、`init-perms-controller`、`controller`。
+- **Web UI**: `web`。
+- **共有初期化**: `init-config-perms`。
+- **エージェントスタック**: `init-perms-agent`、`agent`。
+
+オールインワンデプロイ以外の場合は、トポロジに合わせてこれらのセクションを明示的に分割します。コントローラーと Web は一緒にまたは別々に実行できます。各エージェントノードはエージェントスタックと独自の Docker ソケットアクセスを保持します。
+
+## イメージ
+
+リリースイメージは Forgejo、GHCR、Docker Hub に公開されています:
+
+| コンポーネント | Forgejo | GHCR | Docker Hub |
+|-----------|---------|------|------------|
+| CLI | `forgejo.alexma.top/alexma233/composia-cli` | `ghcr.io/alexma233/composia-cli` | `alexma233/composia-cli` |
+| コントローラー | `forgejo.alexma.top/alexma233/composia-controller` | `ghcr.io/alexma233/composia-controller` | `alexma233/composia-controller` |
+| エージェント | `forgejo.alexma.top/alexma233/composia-agent` | `ghcr.io/alexma233/composia-agent` | `alexma233/composia-agent` |
+| Web | `forgejo.alexma.top/alexma233/composia-web` | `ghcr.io/alexma233/composia-web` | `alexma233/composia-web` |
+
+Canary イメージは Forgejo と GHCR にのみ公開されています。
+
+## 一般的なチェック
+
+- コントローラーが起動できない: `config.yaml` が `COMPOSIA_CONFIG_DIR` 以下に存在し、必要なコントローラーパスが存在するか作成可能であることを確認します。
+- エージェントが Docker を使用できない: `DOCKER_SOCK_GID` がホストの `/var/run/docker.sock` と一致することを確認します。
+- Web がコントローラーに到達できない: `WEB_CONTROLLER_ADDR` は Web サーバーコンテナ用で、`WEB_BROWSER_CONTROLLER_ADDR` はブラウザ用です。
diff --git a/site/content/docs/installation/docker-compose.zh-hans.md b/site/content/docs/installation/docker-compose.zh-hans.md
new file mode 100644
index 0000000..de03f8d
--- /dev/null
+++ b/site/content/docs/installation/docker-compose.zh-hans.md
@@ -0,0 +1,120 @@
+---
+title: "Docker Compose"
+date: '2026-05-26T00:00:00+08:00'
+weight: 20
+---
+
+Docker Compose 堆栈使用官方的 [`docker-compose.yaml`](https://forgejo.alexma.top/alexma233/composia/src/branch/main/docker-compose.yaml) 运行控制器、一个本地 agent 和 Web UI。
+
+## 下载文件
+
+您无需克隆整个仓库来进行 Docker Compose 安装。下载 compose 文件和环境模板：
+
+```bash
+curl -LO https://forgejo.alexma.top/alexma233/composia/raw/branch/main/docker-compose.yaml
+curl -L https://forgejo.alexma.top/alexma233/composia/raw/branch/main/.env.example -o .env
+```
+
+在启动堆栈之前编辑 `.env`。模板按角色分组；对于一体化堆栈，保留所有组。各变量的含义请参阅[配置](../configuration/)。
+
+查找主机上 Docker 套接字的组 ID：
+
+```bash
+stat -c '%g' /var/run/docker.sock
+```
+
+将 `DOCKER_SOCK_GID` 设置为该值。
+
+## Agent 仓库路径
+
+`COMPOSIA_AGENT_REPO_DIR` 的挂载方式为：
+
+```yaml
+- ${COMPOSIA_AGENT_REPO_DIR}:${COMPOSIA_AGENT_REPO_DIR}
+```
+
+主机路径和容器路径必须相同。Agent 调用主机 Docker 守护进程，主机 Docker 守护进程从主机文件系统解析绑定挂载。如果服务仓库在 agent 容器内挂载到不同路径，Docker Compose 可能会生成不存在的主机路径。
+
+在两侧使用相同的绝对路径，例如：
+
+```bash
+COMPOSIA_AGENT_REPO_DIR=/srv/composia/repo-agent
+```
+
+## 基础 `config.yaml`
+
+在 `COMPOSIA_CONFIG_DIR` 内创建 `config.yaml`。Docker Compose 文件将此目录挂载到 `/app/configs`。
+
+```yaml {filename="config.yaml"}
+controller:
+ listen_addr: ":7001"
+ repo_dir: "/data/repo-controller"
+ state_dir: "/data/state-controller"
+ log_dir: "/data/logs"
+ access_tokens:
+ - name: "web"
+ token: "REPLACE_WITH_WEB_ACCESS_TOKEN"
+ enabled: true
+ nodes:
+ - id: "main"
+ display_name: "Main"
+ enabled: true
+ token: "REPLACE_WITH_MAIN_AGENT_TOKEN"
+agent:
+ controller_addr: "http://controller:7001"
+ node_id: "main"
+ token: "REPLACE_WITH_MAIN_AGENT_TOKEN"
+ repo_dir: "/data/repo-agent"
+ state_dir: "/data/state-agent"
+```
+
+在 `.env` 中将 `WEB_CONTROLLER_ACCESS_TOKEN` 设置为与 `controller.access_tokens[0].token` 相同的值。
+
+## Web 密码
+
+`WEB_LOGIN_PASSWORD_HASH` 必须是 Argon2 密码哈希。使用支持 Argon2 的密码哈希工具，并将完整的编码哈希粘贴到 `.env` 中。
+
+使用任何密码学安全的随机生成器生成 `WEB_SESSION_SECRET`，例如：
+
+```bash
+openssl rand -hex 32
+```
+
+## 启动
+
+```bash
+docker compose up -d
+docker compose ps
+```
+
+在 `http://localhost:3000` 打开 Web UI。
+
+## 角色拆分
+
+Compose 文件按角色分段：
+
+- **控制器堆栈**: `init-repo-controller`、`init-perms-controller`、`controller`。
+- **Web UI**: `web`。
+- **共享初始化**: `init-config-perms`。
+- **Agent 堆栈**: `init-perms-agent`、`agent`。
+
+对于一体化部署以外的场景，请根据您的拓扑显式拆分这些部分。控制器和 Web 可以一起运行，也可以分开运行。每个 agent 节点保留 agent 堆栈及其自己的 Docker 套接字访问。
+
+## 镜像
+
+发布镜像发布到 Forgejo、GHCR 和 Docker Hub：
+
+| 组件 | Forgejo | GHCR | Docker Hub |
+|-----------|---------|------|------------|
+| CLI | `forgejo.alexma.top/alexma233/composia-cli` | `ghcr.io/alexma233/composia-cli` | `alexma233/composia-cli` |
+| Controller | `forgejo.alexma.top/alexma233/composia-controller` | `ghcr.io/alexma233/composia-controller` | `alexma233/composia-controller` |
+| Agent | `forgejo.alexma.top/alexma233/composia-agent` | `ghcr.io/alexma233/composia-agent` | `alexma233/composia-agent` |
+| Web | `forgejo.alexma.top/alexma233/composia-web` | `ghcr.io/alexma233/composia-web` | `alexma233/composia-web` |
+
+Canary 镜像仅发布到 Forgejo 和 GHCR。
+
+## 常见检查
+
+- 控制器无法启动：验证 `config.yaml` 是否存在于 `COMPOSIA_CONFIG_DIR` 下，以及所需的控制器路径是否存在或可以创建。
+- Agent 无法使用 Docker：验证 `DOCKER_SOCK_GID` 与主机上 `/var/run/docker.sock` 的组 ID 匹配。
+- Web 无法连接控制器：`WEB_CONTROLLER_ADDR` 用于 Web 服务器容器，而 `WEB_BROWSER_CONTROLLER_ADDR` 用于浏览器。
diff --git a/site/content/docs/installation/docker-compose.zh-hant.md b/site/content/docs/installation/docker-compose.zh-hant.md
new file mode 100644
index 0000000..0db6433
--- /dev/null
+++ b/site/content/docs/installation/docker-compose.zh-hant.md
@@ -0,0 +1,120 @@
+---
+title: "Docker Compose"
+date: '2026-05-26T00:00:00+08:00'
+weight: 20
+---
+
+Docker Compose 堆疊從官方 [`docker-compose.yaml`](https://forgejo.alexma.top/alexma233/composia/src/branch/main/docker-compose.yaml) 執行控制器、一個本地代理和 Web UI。
+
+## 下載檔案
+
+使用 Docker Compose 安裝不需要複製整個存放庫。下載 compose 檔案和環境範本：
+
+```bash
+curl -LO https://forgejo.alexma.top/alexma233/composia/raw/branch/main/docker-compose.yaml
+curl -L https://forgejo.alexma.top/alexma233/composia/raw/branch/main/.env.example -o .env
+```
+
+在啟動堆疊前編輯 `.env`。範本按角色分組；對於整合式堆疊，保留所有組別。各變數的意義請參見[設定](../configuration/)。
+
+在主機上找到 Docker socket 群組 ID：
+
+```bash
+stat -c '%g' /var/run/docker.sock
+```
+
+將 `DOCKER_SOCK_GID` 設定為該值。
+
+## 代理存放庫路徑
+
+`COMPOSIA_AGENT_REPO_DIR` 掛載為：
+
+```yaml
+- ${COMPOSIA_AGENT_REPO_DIR}:${COMPOSIA_AGENT_REPO_DIR}
+```
+
+主機路徑和容器路徑必須相同。代理呼叫主機 Docker 守護程序，而主機 Docker 守護程序從主機檔案系統解析繫結掛載。如果服務存放庫在代理容器內掛載到不同路徑，Docker Compose 可能會產生不存在的主機路徑。
+
+在兩側使用相同的絕對路徑，例如：
+
+```bash
+COMPOSIA_AGENT_REPO_DIR=/srv/composia/repo-agent
+```
+
+## 基本的 `config.yaml`
+
+在 `COMPOSIA_CONFIG_DIR` 內建立 `config.yaml`。Docker Compose 檔案將此目錄掛載到 `/app/configs`。
+
+```yaml {filename="config.yaml"}
+controller:
+ listen_addr: ":7001"
+ repo_dir: "/data/repo-controller"
+ state_dir: "/data/state-controller"
+ log_dir: "/data/logs"
+ access_tokens:
+ - name: "web"
+ token: "REPLACE_WITH_WEB_ACCESS_TOKEN"
+ enabled: true
+ nodes:
+ - id: "main"
+ display_name: "Main"
+ enabled: true
+ token: "REPLACE_WITH_MAIN_AGENT_TOKEN"
+agent:
+ controller_addr: "http://controller:7001"
+ node_id: "main"
+ token: "REPLACE_WITH_MAIN_AGENT_TOKEN"
+ repo_dir: "/data/repo-agent"
+ state_dir: "/data/state-agent"
+```
+
+將 `.env` 中的 `WEB_CONTROLLER_ACCESS_TOKEN` 設定為與 `controller.access_tokens[0].token` 相同的值。
+
+## Web 密碼
+
+`WEB_LOGIN_PASSWORD_HASH` 必須是 Argon2 密碼雜湊。使用支援 Argon2 的密碼雜湊工具，並將完整的編碼雜湊貼入 `.env`。
+
+使用任何密碼學安全的隨機產生器來產生 `WEB_SESSION_SECRET`，例如：
+
+```bash
+openssl rand -hex 32
+```
+
+## 啟動
+
+```bash
+docker compose up -d
+docker compose ps
+```
+
+在 `http://localhost:3000` 開啟 Web UI。
+
+## 角色拆分
+
+Compose 檔案按角色分區：
+
+- **控制器堆疊**：`init-repo-controller`、`init-perms-controller`、`controller`。
+- **Web UI**：`web`。
+- **共用初始化**：`init-config-perms`。
+- **代理堆疊**：`init-perms-agent`、`agent`。
+
+對於整合式部署以外的任何情況，根據您的拓撲明確拆分這些區段。控制器和 Web 可以一起執行或分開執行。每個代理節點保留代理堆疊及其自身的 Docker socket 存取。
+
+## 映像檔
+
+發行版本映像檔發布到 Forgejo、GHCR 和 Docker Hub：
+
+| 元件 | Forgejo | GHCR | Docker Hub |
+|-----------|---------|------|------------|
+| CLI | `forgejo.alexma.top/alexma233/composia-cli` | `ghcr.io/alexma233/composia-cli` | `alexma233/composia-cli` |
+| Controller | `forgejo.alexma.top/alexma233/composia-controller` | `ghcr.io/alexma233/composia-controller` | `alexma233/composia-controller` |
+| Agent | `forgejo.alexma.top/alexma233/composia-agent` | `ghcr.io/alexma233/composia-agent` | `alexma233/composia-agent` |
+| Web | `forgejo.alexma.top/alexma233/composia-web` | `ghcr.io/alexma233/composia-web` | `alexma233/composia-web` |
+
+Canary 映像檔僅發布到 Forgejo 和 GHCR。
+
+## 常見檢查
+
+- 控制器無法啟動：驗證 `config.yaml` 是否存在於 `COMPOSIA_CONFIG_DIR` 下，且必要的控制器路徑存在或可建立。
+- 代理無法使用 Docker：驗證 `DOCKER_SOCK_GID` 與主機上的 `/var/run/docker.sock` 匹配。
+- Web 無法連接控制器：`WEB_CONTROLLER_ADDR` 用於 Web 伺服器容器，而 `WEB_BROWSER_CONTROLLER_ADDR` 用於瀏覽器。
diff --git a/site/content/docs/installation/package-managers.de.md b/site/content/docs/installation/package-managers.de.md
new file mode 100644
index 0000000..45d567a
--- /dev/null
+++ b/site/content/docs/installation/package-managers.de.md
@@ -0,0 +1,212 @@
+---
+title: "Paketmanager und Binärdateien"
+date: '2026-05-26T00:00:00+08:00'
+weight: 30
+---
+
+Verwende diese Seite für Nicht-Container-Installationen und manuelle Binär-Downloads.
+
+## Laufzeitwerkzeuge
+
+Container-Images enthalten diese Werkzeuge bereits. Nicht-Container-Installationen müssen sie auf dem Host bereitstellen.
+
+| Host-Rolle | Erforderliche Werkzeuge |
+|-----------|----------------|
+| Controller | CA-Zertifikate, `git`. |
+| Agent | `git`, Docker CLI, Docker Buildx-Plugin, Docker Compose-Plugin, Zugriff auf den Docker-Daemon. |
+
+Die Paket- oder Archivinstallation installiert nur Composia-Binärdateien. Sie installiert Docker, Docker Compose oder Git nicht für dich.
+
+{{< tabs >}}
+
+{{< tab name="APT" >}}
+## Debian und Ubuntu
+
+Füge das Forgejo-APT-Repository hinzu:
+
+```bash
+sudo install -d -m 0755 /etc/apt/keyrings
+sudo curl https://forgejo.alexma.top/api/packages/alexma233/debian/repository.key \
+ -o /etc/apt/keyrings/composia.asc
+
+echo "deb [signed-by=/etc/apt/keyrings/composia.asc] https://forgejo.alexma.top/api/packages/alexma233/debian stable main" \
+ | sudo tee /etc/apt/sources.list.d/composia.list
+
+sudo apt update
+sudo apt install composia
+```
+
+Du kannst auch das `.deb`-Paket von der [Releases-Seite](https://forgejo.alexma.top/alexma233/composia/releases) herunterladen und mit deinem Paketmanager installieren.
+
+Überprüfen:
+
+```bash
+composia --version
+```
+{{< /tab >}}
+
+{{< tab name="RPM / COPR" >}}
+## Fedora, RHEL und kompatible Distributionen
+
+Verwende COPR auf Fedora:
+
+```bash
+sudo dnf copr enable alexma233/composia
+sudo dnf install composia
+```
+
+Du kannst auch das `.rpm`-Paket von der [Releases-Seite](https://forgejo.alexma.top/alexma233/composia/releases) herunterladen und mit `dnf` oder `yum` installieren.
+
+Überprüfen:
+
+```bash
+composia --version
+```
+{{< /tab >}}
+
+{{< tab name="Arch / AUR" >}}
+## Arch Linux
+
+Zwei AUR-Pakete werden veröffentlicht:
+
+| Paket | Quelle |
+|---------|--------|
+| `composia-bin` | Vorgefertigte Release-Binärdateien. |
+| `composia` | Aus dem Quellcode gebaut. |
+
+Installiere eines davon mit deinem AUR-Helper:
+
+```bash
+paru -S composia-bin
+```
+
+oder:
+
+```bash
+paru -S composia
+```
+
+Die beiden Pakete stehen miteinander in Konflikt. Installiere nur eines.
+
+Du kannst auch das `.pkg.tar.zst`-Paket von der [Releases-Seite](https://forgejo.alexma.top/alexma233/composia/releases) herunterladen und mit `pacman -U` installieren.
+
+Überprüfen:
+
+```bash
+composia --version
+```
+{{< /tab >}}
+
+{{< tab name="Nix" >}}
+## Nix Flake
+
+Installiere aus dem Repository-Flake:
+
+```bash
+nix profile install git+https://forgejo.alexma.top/alexma233/composia
+```
+
+Führe eine Binärdatei direkt aus:
+
+```bash
+nix run git+https://forgejo.alexma.top/alexma233/composia#composia
+nix run git+https://forgejo.alexma.top/alexma233/composia#composia-controller
+nix run git+https://forgejo.alexma.top/alexma233/composia#composia-agent
+```
+
+Unterstützte Flake-Systeme: `x86_64-linux`, `aarch64-linux`, `i686-linux`, `armv7l-linux`, `riscv64-linux`.
+
+Das nixpkgs-Paket ist noch nicht zusammengeführt. Verfolge den Upstream-PR unter [NixOS/nixpkgs#515061](https://github.com/NixOS/nixpkgs/pull/515061). Bis es verfügbar ist, verwende das Flake.
+{{< /tab >}}
+
+{{< tab name="Manuelle Binärdatei" >}}
+## Manueller Binär-Download
+
+Lade Archive von der [Releases-Seite](https://forgejo.alexma.top/alexma233/composia/releases) herunter.
+
+### Artefakte
+
+| Plattform | Artefaktmuster | Inhalt |
+|----------|------------------|----------|
+| Linux | `composia__linux_.tar.gz` | `composia`, `composia-controller`, `composia-agent` |
+| macOS | `composia__darwin_.tar.gz` | `composia` |
+| Windows | `composia__windows_.zip` | `composia.exe` |
+
+Linux-Architekturen: `amd64`, `arm64`, `armv7`, `386`, `riscv64`.
+
+macOS-Architekturen: `amd64`, `arm64`.
+
+Windows-Architekturen: `amd64`, `arm64`, `386`.
+
+### Nach dem Download installieren
+
+Linux-Archiv:
+
+```bash
+tar xzf composia__linux_.tar.gz
+sudo install -m 755 composia composia-controller composia-agent /usr/local/bin/
+```
+
+macOS-Archiv:
+
+```bash
+tar xzf composia__darwin_.tar.gz
+sudo install -m 755 composia /usr/local/bin/
+```
+
+Windows-Archiv:
+
+```powershell
+Expand-Archive composia__windows_.zip -DestinationPath .
+```
+
+Platziere `composia.exe` irgendwo in `%PATH%`.
+
+### Prüfsummen überprüfen
+
+Lade `checksums.txt` vom selben Release herunter und überprüfe das heruntergeladene Artefakt mit dem SHA-256-Werkzeug deiner Plattform.
+{{< /tab >}}
+
+{{< /tabs >}}
+
+## Systemdienste
+
+Wenn du Controller oder Agent außerhalb von Containern betreibst, verwende deinen Service-Manager, um sie am Laufen zu halten.
+
+Beispiel systemd-Controller-Unit:
+
+```ini {filename="/etc/systemd/system/composia-controller.service"}
+[Unit]
+Description=Composia Controller
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+ExecStart=/usr/bin/composia-controller -config /etc/composia/config.yaml
+Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Beispiel systemd-Agent-Unit:
+
+```ini {filename="/etc/systemd/system/composia-agent.service"}
+[Unit]
+Description=Composia Agent
+After=network-online.target docker.service
+Wants=network-online.target docker.service
+
+[Service]
+Type=simple
+ExecStart=/usr/bin/composia-agent -config /etc/composia/config.yaml
+Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Passe Benutzer, Gruppen, Konfigurationspfade und Docker-Socket-Berechtigungen an deine Umgebung an.
diff --git a/site/content/docs/installation/package-managers.fr.md b/site/content/docs/installation/package-managers.fr.md
new file mode 100644
index 0000000..7e63c3c
--- /dev/null
+++ b/site/content/docs/installation/package-managers.fr.md
@@ -0,0 +1,212 @@
+---
+title: "Gestionnaires de paquets et binaires"
+date: '2026-05-26T00:00:00+08:00'
+weight: 30
+---
+
+Utilisez cette page pour les installations sans conteneur et les téléchargements manuels de binaires.
+
+## Outils d'exécution
+
+Les images de conteneur incluent déjà ces outils. Les installations sans conteneur doivent les fournir sur l'hôte.
+
+| Rôle hôte | Outils requis |
+|-----------|----------------|
+| Contrôleur | Certificats CA, `git`. |
+| Agent | `git`, Docker CLI, plugin Docker Buildx, plugin Docker Compose, accès au démon Docker. |
+
+Le paquet ou l'archive installe uniquement les binaires Composia. Il n'installe pas Docker, Docker Compose ou Git pour vous.
+
+{{< tabs >}}
+
+{{< tab name="APT" >}}
+## Debian et Ubuntu
+
+Ajoutez le dépôt APT Forgejo :
+
+```bash
+sudo install -d -m 0755 /etc/apt/keyrings
+sudo curl https://forgejo.alexma.top/api/packages/alexma233/debian/repository.key \
+ -o /etc/apt/keyrings/composia.asc
+
+echo "deb [signed-by=/etc/apt/keyrings/composia.asc] https://forgejo.alexma.top/api/packages/alexma233/debian stable main" \
+ | sudo tee /etc/apt/sources.list.d/composia.list
+
+sudo apt update
+sudo apt install composia
+```
+
+Vous pouvez également télécharger le paquet `.deb` depuis la [page des Releases](https://forgejo.alexma.top/alexma233/composia/releases) et l'installer avec votre gestionnaire de paquets.
+
+Vérifiez :
+
+```bash
+composia --version
+```
+{{< /tab >}}
+
+{{< tab name="RPM / COPR" >}}
+## Fedora, RHEL et distributions compatibles
+
+Utilisez COPR sur Fedora :
+
+```bash
+sudo dnf copr enable alexma233/composia
+sudo dnf install composia
+```
+
+Vous pouvez également télécharger le paquet `.rpm` depuis la [page des Releases](https://forgejo.alexma.top/alexma233/composia/releases) et l'installer avec `dnf` ou `yum`.
+
+Vérifiez :
+
+```bash
+composia --version
+```
+{{< /tab >}}
+
+{{< tab name="Arch / AUR" >}}
+## Arch Linux
+
+Deux paquets AUR sont publiés :
+
+| Paquet | Source |
+|---------|--------|
+| `composia-bin` | Binaires de release précompilés. |
+| `composia` | Compilé depuis les sources. |
+
+Installez l'un d'eux avec votre helper AUR :
+
+```bash
+paru -S composia-bin
+```
+
+ou :
+
+```bash
+paru -S composia
+```
+
+Les deux paquets sont en conflit l'un avec l'autre. N'en installez qu'un seul.
+
+Vous pouvez également télécharger le paquet `.pkg.tar.zst` depuis la [page des Releases](https://forgejo.alexma.top/alexma233/composia/releases) et l'installer avec `pacman -U`.
+
+Vérifiez :
+
+```bash
+composia --version
+```
+{{< /tab >}}
+
+{{< tab name="Nix" >}}
+## Nix Flake
+
+Installez depuis le flake du dépôt :
+
+```bash
+nix profile install git+https://forgejo.alexma.top/alexma233/composia
+```
+
+Exécutez un binaire directement :
+
+```bash
+nix run git+https://forgejo.alexma.top/alexma233/composia#composia
+nix run git+https://forgejo.alexma.top/alexma233/composia#composia-controller
+nix run git+https://forgejo.alexma.top/alexma233/composia#composia-agent
+```
+
+Systèmes flake pris en charge : `x86_64-linux`, `aarch64-linux`, `i686-linux`, `armv7l-linux`, `riscv64-linux`.
+
+Le paquet nixpkgs n'est pas encore fusionné. Suivez la PR upstream sur [NixOS/nixpkgs#515061](https://github.com/NixOS/nixpkgs/pull/515061). En attendant, utilisez le flake.
+{{< /tab >}}
+
+{{< tab name="Binaire manuel" >}}
+## Téléchargement manuel de binaires
+
+Téléchargez les archives depuis la [page des Releases](https://forgejo.alexma.top/alexma233/composia/releases).
+
+### Artefacts
+
+| Plateforme | Modèle d'artefact | Contenu |
+|----------|------------------|----------|
+| Linux | `composia__linux_.tar.gz` | `composia`, `composia-controller`, `composia-agent` |
+| macOS | `composia__darwin_.tar.gz` | `composia` |
+| Windows | `composia__windows_.zip` | `composia.exe` |
+
+Architectures Linux : `amd64`, `arm64`, `armv7`, `386`, `riscv64`.
+
+Architectures macOS : `amd64`, `arm64`.
+
+Architectures Windows : `amd64`, `arm64`, `386`.
+
+### Installation après téléchargement
+
+Archive Linux :
+
+```bash
+tar xzf composia__linux_.tar.gz
+sudo install -m 755 composia composia-controller composia-agent /usr/local/bin/
+```
+
+Archive macOS :
+
+```bash
+tar xzf composia__darwin_.tar.gz
+sudo install -m 755 composia /usr/local/bin/
+```
+
+Archive Windows :
+
+```powershell
+Expand-Archive composia__windows_.zip -DestinationPath .
+```
+
+Placez `composia.exe` quelque part dans `%PATH%`.
+
+### Vérifier les sommes de contrôle
+
+Téléchargez `checksums.txt` depuis la même release et vérifiez l'artefact téléchargé avec l'outil SHA-256 de votre plateforme.
+{{< /tab >}}
+
+{{< /tabs >}}
+
+## Services système
+
+Lorsque vous exécutez le contrôleur ou l'agent en dehors des conteneurs, utilisez votre gestionnaire de services pour les maintenir en cours d'exécution.
+
+Exemple d'unité systemd pour le contrôleur :
+
+```ini {filename="/etc/systemd/system/composia-controller.service"}
+[Unit]
+Description=Composia Controller
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+ExecStart=/usr/bin/composia-controller -config /etc/composia/config.yaml
+Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Exemple d'unité systemd pour l'agent :
+
+```ini {filename="/etc/systemd/system/composia-agent.service"}
+[Unit]
+Description=Composia Agent
+After=network-online.target docker.service
+Wants=network-online.target docker.service
+
+[Service]
+Type=simple
+ExecStart=/usr/bin/composia-agent -config /etc/composia/config.yaml
+Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Adaptez les utilisateurs, groupes, chemins de configuration et permissions du socket Docker à votre environnement.
diff --git a/site/content/docs/installation/package-managers.ja.md b/site/content/docs/installation/package-managers.ja.md
new file mode 100644
index 0000000..45f0c0c
--- /dev/null
+++ b/site/content/docs/installation/package-managers.ja.md
@@ -0,0 +1,212 @@
+---
+title: "パッケージマネージャーとバイナリ"
+date: '2026-05-26T00:00:00+08:00'
+weight: 30
+---
+
+このページは非コンテナインストールと手動バイナリダウンロード向けです。
+
+## ランタイムツール
+
+コンテナイメージにはこれらのツールがすでに含まれています。非コンテナインストールではホスト上にこれらを用意する必要があります。
+
+| ホストロール | 必要なツール |
+|-----------|----------------|
+| コントローラー | CA 証明書、`git`。 |
+| エージェント | `git`、Docker CLI、Docker Buildx プラグイン、Docker Compose プラグイン、Docker デーモンへのアクセス。 |
+
+パッケージまたはアーカイブは Composia バイナリのみをインストールします。Docker、Docker Compose、Git はインストールされません。
+
+{{< tabs >}}
+
+{{< tab name="APT" >}}
+## Debian および Ubuntu
+
+Forgejo APT リポジトリを追加します:
+
+```bash
+sudo install -d -m 0755 /etc/apt/keyrings
+sudo curl https://forgejo.alexma.top/api/packages/alexma233/debian/repository.key \
+ -o /etc/apt/keyrings/composia.asc
+
+echo "deb [signed-by=/etc/apt/keyrings/composia.asc] https://forgejo.alexma.top/api/packages/alexma233/debian stable main" \
+ | sudo tee /etc/apt/sources.list.d/composia.list
+
+sudo apt update
+sudo apt install composia
+```
+
+[リリースページ](https://forgejo.alexma.top/alexma233/composia/releases) から `.deb` パッケージをダウンロードし、パッケージマネージャーでインストールすることもできます。
+
+確認:
+
+```bash
+composia --version
+```
+{{< /tab >}}
+
+{{< tab name="RPM / COPR" >}}
+## Fedora、RHEL、および互換ディストリビューション
+
+Fedora では COPR を使用します:
+
+```bash
+sudo dnf copr enable alexma233/composia
+sudo dnf install composia
+```
+
+[リリースページ](https://forgejo.alexma.top/alexma233/composia/releases) から `.rpm` パッケージをダウンロードし、`dnf` または `yum` でインストールすることもできます。
+
+確認:
+
+```bash
+composia --version
+```
+{{< /tab >}}
+
+{{< tab name="Arch / AUR" >}}
+## Arch Linux
+
+2 つの AUR パッケージが公開されています:
+
+| パッケージ | ソース |
+|---------|--------|
+| `composia-bin` | ビルド済みリリースバイナリ。 |
+| `composia` | ソースからビルド。 |
+
+AUR ヘルパーでいずれかをインストールします:
+
+```bash
+paru -S composia-bin
+```
+
+または:
+
+```bash
+paru -S composia
+```
+
+2 つのパッケージは互いに競合します。いずれか 1 つだけをインストールしてください。
+
+[リリースページ](https://forgejo.alexma.top/alexma233/composia/releases) から `.pkg.tar.zst` パッケージをダウンロードし、`pacman -U` でインストールすることもできます。
+
+確認:
+
+```bash
+composia --version
+```
+{{< /tab >}}
+
+{{< tab name="Nix" >}}
+## Nix Flake
+
+リポジトリフレークからインストールします:
+
+```bash
+nix profile install git+https://forgejo.alexma.top/alexma233/composia
+```
+
+バイナリを直接実行:
+
+```bash
+nix run git+https://forgejo.alexma.top/alexma233/composia#composia
+nix run git+https://forgejo.alexma.top/alexma233/composia#composia-controller
+nix run git+https://forgejo.alexma.top/alexma233/composia#composia-agent
+```
+
+対応フレークシステム: `x86_64-linux`、`aarch64-linux`、`i686-linux`、`armv7l-linux`、`riscv64-linux`。
+
+nixpkgs パッケージはまだマージされていません。上流の PR を [NixOS/nixpkgs#515061](https://github.com/NixOS/nixpkgs/pull/515061) で追跡してください。マージされるまではフレークを使用してください。
+{{< /tab >}}
+
+{{< tab name="手動バイナリ" >}}
+## 手動バイナリダウンロード
+
+[リリースページ](https://forgejo.alexma.top/alexma233/composia/releases) からアーカイブをダウンロードします。
+
+### 成果物
+
+| プラットフォーム | 成果物パターン | 内容 |
+|----------|------------------|----------|
+| Linux | `composia__linux_.tar.gz` | `composia`、`composia-controller`、`composia-agent` |
+| macOS | `composia__darwin_.tar.gz` | `composia` |
+| Windows | `composia__windows_.zip` | `composia.exe` |
+
+Linux アーキテクチャ: `amd64`、`arm64`、`armv7`、`386`、`riscv64`。
+
+macOS アーキテクチャ: `amd64`、`arm64`。
+
+Windows アーキテクチャ: `amd64`、`arm64`、`386`。
+
+### ダウンロード後のインストール
+
+Linux アーカイブ:
+
+```bash
+tar xzf composia__linux_.tar.gz
+sudo install -m 755 composia composia-controller composia-agent /usr/local/bin/
+```
+
+macOS アーカイブ:
+
+```bash
+tar xzf composia__darwin_.tar.gz
+sudo install -m 755 composia /usr/local/bin/
+```
+
+Windows アーカイブ:
+
+```powershell
+Expand-Archive composia__windows_.zip -DestinationPath .
+```
+
+`composia.exe` を `%PATH%` のどこかに配置します。
+
+### チェックサムの検証
+
+同じリリースから `checksums.txt` をダウンロードし、お使いのプラットフォームの SHA-256 ツールでダウンロードした成果物を検証します。
+{{< /tab >}}
+
+{{< /tabs >}}
+
+## システムサービス
+
+コントローラーまたはエージェントをコンテナ外で実行する場合、サービスマネージャーを使用して実行を維持します。
+
+systemd コントローラーユニットの例:
+
+```ini {filename="/etc/systemd/system/composia-controller.service"}
+[Unit]
+Description=Composia Controller
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+ExecStart=/usr/bin/composia-controller -config /etc/composia/config.yaml
+Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+```
+
+systemd エージェントユニットの例:
+
+```ini {filename="/etc/systemd/system/composia-agent.service"}
+[Unit]
+Description=Composia Agent
+After=network-online.target docker.service
+Wants=network-online.target docker.service
+
+[Service]
+Type=simple
+ExecStart=/usr/bin/composia-agent -config /etc/composia/config.yaml
+Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+```
+
+ユーザー、グループ、設定パス、Docker ソケット権限は環境に合わせて調整してください。
diff --git a/site/content/docs/installation/package-managers.zh-hans.md b/site/content/docs/installation/package-managers.zh-hans.md
new file mode 100644
index 0000000..f3b1dd8
--- /dev/null
+++ b/site/content/docs/installation/package-managers.zh-hans.md
@@ -0,0 +1,212 @@
+---
+title: "包管理器与二进制文件"
+date: '2026-05-26T00:00:00+08:00'
+weight: 30
+---
+
+本页适用于非容器安装和手动下载二进制文件。
+
+## 运行时工具
+
+容器镜像已包含这些工具。非容器安装必须在主机上提供它们。
+
+| 主机角色 | 必需工具 |
+|-----------|----------------|
+| Controller | CA 证书、`git`。 |
+| Agent | `git`、Docker CLI、Docker Buildx 插件、Docker Compose 插件、Docker 守护进程访问权限。 |
+
+软件包或归档仅安装 Composia 二进制文件。它不会为您安装 Docker、Docker Compose 或 Git。
+
+{{< tabs >}}
+
+{{< tab name="APT" >}}
+## Debian 和 Ubuntu
+
+添加 Forgejo APT 仓库：
+
+```bash
+sudo install -d -m 0755 /etc/apt/keyrings
+sudo curl https://forgejo.alexma.top/api/packages/alexma233/debian/repository.key \
+ -o /etc/apt/keyrings/composia.asc
+
+echo "deb [signed-by=/etc/apt/keyrings/composia.asc] https://forgejo.alexma.top/api/packages/alexma233/debian stable main" \
+ | sudo tee /etc/apt/sources.list.d/composia.list
+
+sudo apt update
+sudo apt install composia
+```
+
+您也可以从[发布页面](https://forgejo.alexma.top/alexma233/composia/releases)下载 `.deb` 包并使用包管理器安装。
+
+验证：
+
+```bash
+composia --version
+```
+{{< /tab >}}
+
+{{< tab name="RPM / COPR" >}}
+## Fedora、RHEL 及兼容发行版
+
+在 Fedora 上使用 COPR：
+
+```bash
+sudo dnf copr enable alexma233/composia
+sudo dnf install composia
+```
+
+您也可以从[发布页面](https://forgejo.alexma.top/alexma233/composia/releases)下载 `.rpm` 包并使用 `dnf` 或 `yum` 安装。
+
+验证：
+
+```bash
+composia --version
+```
+{{< /tab >}}
+
+{{< tab name="Arch / AUR" >}}
+## Arch Linux
+
+发布有两个 AUR 包：
+
+| 包 | 来源 |
+|---------|--------|
+| `composia-bin` | 预构建的发布二进制文件。 |
+| `composia` | 从源码构建。 |
+
+使用您的 AUR 助手安装其中之一：
+
+```bash
+paru -S composia-bin
+```
+
+或：
+
+```bash
+paru -S composia
+```
+
+两个包互斥。只能安装其中一个。
+
+您也可以从[发布页面](https://forgejo.alexma.top/alexma233/composia/releases)下载 `.pkg.tar.zst` 包并使用 `pacman -U` 安装。
+
+验证：
+
+```bash
+composia --version
+```
+{{< /tab >}}
+
+{{< tab name="Nix" >}}
+## Nix Flake
+
+从仓库 flake 安装：
+
+```bash
+nix profile install git+https://forgejo.alexma.top/alexma233/composia
+```
+
+直接运行二进制文件：
+
+```bash
+nix run git+https://forgejo.alexma.top/alexma233/composia#composia
+nix run git+https://forgejo.alexma.top/alexma233/composia#composia-controller
+nix run git+https://forgejo.alexma.top/alexma233/composia#composia-agent
+```
+
+支持的 flake 系统：`x86_64-linux`、`aarch64-linux`、`i686-linux`、`armv7l-linux`、`riscv64-linux`。
+
+nixpkgs 包尚未合并。请关注上游 PR [NixOS/nixpkgs#515061](https://github.com/NixOS/nixpkgs/pull/515061)。在此之前，请使用 flake。
+{{< /tab >}}
+
+{{< tab name="手动下载二进制" >}}
+## 手动下载二进制文件
+
+从[发布页面](https://forgejo.alexma.top/alexma233/composia/releases)下载归档文件。
+
+### 产物
+
+| 平台 | 产物模式 | 内容 |
+|----------|------------------|----------|
+| Linux | `composia__linux_.tar.gz` | `composia`、`composia-controller`、`composia-agent` |
+| macOS | `composia__darwin_.tar.gz` | `composia` |
+| Windows | `composia__windows_.zip` | `composia.exe` |
+
+Linux 架构：`amd64`、`arm64`、`armv7`、`386`、`riscv64`。
+
+macOS 架构：`amd64`、`arm64`。
+
+Windows 架构：`amd64`、`arm64`、`386`。
+
+### 下载后安装
+
+Linux 归档：
+
+```bash
+tar xzf composia__linux_.tar.gz
+sudo install -m 755 composia composia-controller composia-agent /usr/local/bin/
+```
+
+macOS 归档：
+
+```bash
+tar xzf composia__darwin_.tar.gz
+sudo install -m 755 composia /usr/local/bin/
+```
+
+Windows 归档：
+
+```powershell
+Expand-Archive composia__windows_.zip -DestinationPath .
+```
+
+将 `composia.exe` 放在 `%PATH%` 中的某个位置。
+
+### 验证校验和
+
+从同一发布版本下载 `checksums.txt`，并使用您平台的 SHA-256 工具验证下载的产物。
+{{< /tab >}}
+
+{{< /tabs >}}
+
+## 系统服务
+
+在容器外运行控制器或 agent 时，使用您的服务管理器使它们保持运行。
+
+systemd 控制器单元示例：
+
+```ini {filename="/etc/systemd/system/composia-controller.service"}
+[Unit]
+Description=Composia Controller
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+ExecStart=/usr/bin/composia-controller -config /etc/composia/config.yaml
+Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+```
+
+systemd agent 单元示例：
+
+```ini {filename="/etc/systemd/system/composia-agent.service"}
+[Unit]
+Description=Composia Agent
+After=network-online.target docker.service
+Wants=network-online.target docker.service
+
+[Service]
+Type=simple
+ExecStart=/usr/bin/composia-agent -config /etc/composia/config.yaml
+Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+```
+
+根据您的环境调整用户、组、配置路径和 Docker 套接字权限。
diff --git a/site/content/docs/installation/package-managers.zh-hant.md b/site/content/docs/installation/package-managers.zh-hant.md
new file mode 100644
index 0000000..52c0dd1
--- /dev/null
+++ b/site/content/docs/installation/package-managers.zh-hant.md
@@ -0,0 +1,212 @@
+---
+title: "套件管理器與二進位檔"
+date: '2026-05-26T00:00:00+08:00'
+weight: 30
+---
+
+此頁面用於非容器的安裝和手動二進位檔下載。
+
+## 執行時期工具
+
+容器映像檔已包含這些工具。非容器安裝必須在主機上提供它們。
+
+| 主機角色 | 必要工具 |
+|-----------|----------------|
+| 控制器 | CA 憑證、`git`。 |
+| 代理 | `git`、Docker CLI、Docker Buildx 外掛、Docker Compose 外掛、對 Docker 守護程序的存取。 |
+
+套件或壓縮檔僅安裝 Composia 二進位檔。它不會為您安裝 Docker、Docker Compose 或 Git。
+
+{{< tabs >}}
+
+{{< tab name="APT" >}}
+## Debian 與 Ubuntu
+
+加入 Forgejo APT 存放庫：
+
+```bash
+sudo install -d -m 0755 /etc/apt/keyrings
+sudo curl https://forgejo.alexma.top/api/packages/alexma233/debian/repository.key \
+ -o /etc/apt/keyrings/composia.asc
+
+echo "deb [signed-by=/etc/apt/keyrings/composia.asc] https://forgejo.alexma.top/api/packages/alexma233/debian stable main" \
+ | sudo tee /etc/apt/sources.list.d/composia.list
+
+sudo apt update
+sudo apt install composia
+```
+
+您也可以從[發行版本頁面](https://forgejo.alexma.top/alexma233/composia/releases)下載 `.deb` 套件並使用您的套件管理器安裝。
+
+驗證：
+
+```bash
+composia --version
+```
+{{< /tab >}}
+
+{{< tab name="RPM / COPR" >}}
+## Fedora、RHEL 及相容的發行版
+
+在 Fedora 上使用 COPR：
+
+```bash
+sudo dnf copr enable alexma233/composia
+sudo dnf install composia
+```
+
+您也可以從[發行版本頁面](https://forgejo.alexma.top/alexma233/composia/releases)下載 `.rpm` 套件並使用 `dnf` 或 `yum` 安裝。
+
+驗證：
+
+```bash
+composia --version
+```
+{{< /tab >}}
+
+{{< tab name="Arch / AUR" >}}
+## Arch Linux
+
+發布了兩個 AUR 套件：
+
+| 套件 | 來源 |
+|---------|--------|
+| `composia-bin` | 預先建置的發行版本二進位檔。 |
+| `composia` | 從原始碼建置。 |
+
+使用您的 AUR 助手安裝其中之一：
+
+```bash
+paru -S composia-bin
+```
+
+或：
+
+```bash
+paru -S composia
+```
+
+兩個套件互相衝突。僅安裝一個。
+
+您也可以從[發行版本頁面](https://forgejo.alexma.top/alexma233/composia/releases)下載 `.pkg.tar.zst` 套件並使用 `pacman -U` 安裝。
+
+驗證：
+
+```bash
+composia --version
+```
+{{< /tab >}}
+
+{{< tab name="Nix" >}}
+## Nix Flake
+
+從存放庫 flake 安裝：
+
+```bash
+nix profile install git+https://forgejo.alexma.top/alexma233/composia
+```
+
+直接執行二進位檔：
+
+```bash
+nix run git+https://forgejo.alexma.top/alexma233/composia#composia
+nix run git+https://forgejo.alexma.top/alexma233/composia#composia-controller
+nix run git+https://forgejo.alexma.top/alexma233/composia#composia-agent
+```
+
+支援的 flake 系統：`x86_64-linux`、`aarch64-linux`、`i686-linux`、`armv7l-linux`、`riscv64-linux`。
+
+nixpkgs 套件尚未合併。追蹤上游 PR：[NixOS/nixpkgs#515061](https://github.com/NixOS/nixpkgs/pull/515061)。在它合併之前，請使用 flake。
+{{< /tab >}}
+
+{{< tab name="手動二進位檔" >}}
+## 手動二進位檔下載
+
+從[發行版本頁面](https://forgejo.alexma.top/alexma233/composia/releases)下載壓縮檔。
+
+### 成品
+
+| 平台 | 成品模式 | 內容 |
+|----------|------------------|----------|
+| Linux | `composia__linux_.tar.gz` | `composia`、`composia-controller`、`composia-agent` |
+| macOS | `composia__darwin_.tar.gz` | `composia` |
+| Windows | `composia__windows_.zip` | `composia.exe` |
+
+Linux 架構：`amd64`、`arm64`、`armv7`、`386`、`riscv64`。
+
+macOS 架構：`amd64`、`arm64`。
+
+Windows 架構：`amd64`、`arm64`、`386`。
+
+### 下載後安裝
+
+Linux 壓縮檔：
+
+```bash
+tar xzf composia__linux_.tar.gz
+sudo install -m 755 composia composia-controller composia-agent /usr/local/bin/
+```
+
+macOS 壓縮檔：
+
+```bash
+tar xzf composia__darwin_.tar.gz
+sudo install -m 755 composia /usr/local/bin/
+```
+
+Windows 壓縮檔：
+
+```powershell
+Expand-Archive composia__windows_.zip -DestinationPath .
+```
+
+將 `composia.exe` 放到 `%PATH%` 中的某處。
+
+### 驗證校驗碼
+
+從同一發行版本下載 `checksums.txt`，並使用您平台的 SHA-256 工具驗證下載的成品。
+{{< /tab >}}
+
+{{< /tabs >}}
+
+## 系統服務
+
+在容器外執行控制器或代理時，使用您的服務管理器來保持它們執行。
+
+範例 systemd 控制器單元：
+
+```ini {filename="/etc/systemd/system/composia-controller.service"}
+[Unit]
+Description=Composia Controller
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+ExecStart=/usr/bin/composia-controller -config /etc/composia/config.yaml
+Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+```
+
+範例 systemd 代理單元：
+
+```ini {filename="/etc/systemd/system/composia-agent.service"}
+[Unit]
+Description=Composia Agent
+After=network-online.target docker.service
+Wants=network-online.target docker.service
+
+[Service]
+Type=simple
+ExecStart=/usr/bin/composia-agent -config /etc/composia/config.yaml
+Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+```
+
+根據您的環境調整使用者、群組、設定路徑和 Docker socket 權限。
diff --git a/site/hugo.yaml b/site/hugo.yaml
index 60732e8..c82779c 100644
--- a/site/hugo.yaml
+++ b/site/hugo.yaml
@@ -7,10 +7,26 @@ languages:
label: English
locale: en
weight: 1
+ de:
+ label: Deutsch
+ locale: de
+ weight: 2
+ fr:
+ label: Français
+ locale: fr
+ weight: 3
+ ja:
+ label: 日本語
+ locale: ja
+ weight: 4
zh-hans:
label: 简体中文
locale: zh-cn
- weight: 2
+ weight: 5
+ zh-hant:
+ label: 繁體中文
+ locale: zh-tw
+ weight: 6
markup:
goldmark: