restic-profile-cli 0.2.1__tar.gz → 0.3.0__tar.gz

{restic_profile_cli-0.2.1 → restic_profile_cli-0.3.0}/.github/workflows/docs.yaml

@@ -9,7 +9,7 @@ on:
     paths:
       - "docs/**"
       - "README.md"
-      - "zensical.toml"
+      - "mkdocs.yml"
       - ".github/workflows/docs.yaml"
 
 permissions:
@@ -39,7 +39,7 @@ jobs:
         run: uv sync --locked --group docs
 
       - name: Build documentation
-        run: uv run zensical build
+        run: NO_MKDOCS_2_WARNING=1 uv run mkdocs build
 
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v4

{restic_profile_cli-0.2.1 → restic_profile_cli-0.3.0}/AGENTS.md

@@ -9,12 +9,12 @@ setup, usage, and the development workflow.
 ## Environment & Tooling - CRITICAL
 
 - Environment manager: **uv**. Sync with `uv sync --group dev`.
-- Lint & format: **ruff**. Run `just lint` (or `uv run ruff check --fix src/ tests/` then `uv run ruff format src/ tests/`).
+- Lint & format: **ruff**. Run `just lint` (or `uv run ruff check --fix src/ tests/ plugins/` then `uv run ruff format src/ tests/ plugins/`).
 - Type check: **ty** (`astral-sh/ty`). Run `just typecheck`.
 - Test runner: **pytest** (`uv run pytest -v tests/` or `just test`).
 - Ansible lint: `ansible-lint` (global install, see `README.md`).
 - Build: `uv build -v` (or `just build`).
-- Docs: `uv run zensical build` (or `just docs-build`).
+- Docs: `uv run mkdocs build` (or `just docs-build`).
 
 You MUST NOT use `pip`, `poetry`, `pipenv`, `mypy`, `black`, `flake8`, `isort`,
 or `mkdocs` directly. All Python tooling flows through **uv** and **ruff**/**ty**.

{restic_profile_cli-0.2.1 → restic_profile_cli-0.3.0}/CHANGELOG.md

@@ -5,6 +5,18 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2026-07-13
+
+### Added
+
+- Per-profile systemd user-scope support via `systemd_scope: user` and
+  `systemd_user` fields — deploys config to `~/.config/restic-profile/`
+  and systemd units to `~/.config/systemd/user/` with automatic
+  `loginctl enable-linger` and `XDG_RUNTIME_DIR` handling
+- CLI config resolution via XDG search path — when `--config` is omitted,
+  searches `~/.config/restic-profile/restic-profile.toml` then falls back
+  to `/etc/restic-profile/restic-profile.toml`
+
 ## [0.2.1] - 2026-07-07
 
 ### Fixed

{restic_profile_cli-0.2.1 → restic_profile_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: restic-profile-cli
-Version: 0.2.1
+Version: 0.3.0
 Summary: Profile-based restic wrapper with Ansible deployment support
 Project-URL: Homepage, https://github.com/ak1ra-lab/restic-profile
 Project-URL: Repository, https://github.com/ak1ra-lab/restic-profile
@@ -24,6 +24,8 @@ Description-Content-Type: text/markdown
 
 # restic-profile
 
+**English** | [简体中文](README.zh-CN.md)
+
 [![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/ak1ra-lab/restic-profile/.github%2Fworkflows%2Fpublish-to-pypi.yaml)](https://github.com/ak1ra-lab/restic-profile/actions/workflows/publish-to-pypi.yaml)
 [![PyPI - Version](https://img.shields.io/pypi/v/restic-profile-cli)](https://pypi.org/project/restic-profile-cli/)
 [![PyPI - Version](https://img.shields.io/pypi/v/restic-profile-cli?label=test-pypi&pypiBaseUrl=https%3A%2F%2Ftest.pypi.org)](https://test.pypi.org/project/restic-profile-cli/)
@@ -87,4 +89,4 @@ ansible-lint
 
 ## Documentation
 
-The published documentation site lives at <https://ak1ra-lab.github.io/restic-profile/>, and local docs configuration is stored in `zensical.toml`.
+The published documentation site lives at <https://ak1ra-lab.github.io/restic-profile/>, and local docs configuration is stored in `mkdocs.yml`.

{restic_profile_cli-0.2.1 → restic_profile_cli-0.3.0}/README.md

@@ -1,5 +1,7 @@
 # restic-profile
 
+**English** | [简体中文](README.zh-CN.md)
+
 [![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/ak1ra-lab/restic-profile/.github%2Fworkflows%2Fpublish-to-pypi.yaml)](https://github.com/ak1ra-lab/restic-profile/actions/workflows/publish-to-pypi.yaml)
 [![PyPI - Version](https://img.shields.io/pypi/v/restic-profile-cli)](https://pypi.org/project/restic-profile-cli/)
 [![PyPI - Version](https://img.shields.io/pypi/v/restic-profile-cli?label=test-pypi&pypiBaseUrl=https%3A%2F%2Ftest.pypi.org)](https://test.pypi.org/project/restic-profile-cli/)
@@ -63,4 +65,4 @@ ansible-lint
 
 ## Documentation
 
-The published documentation site lives at <https://ak1ra-lab.github.io/restic-profile/>, and local docs configuration is stored in `zensical.toml`.
+The published documentation site lives at <https://ak1ra-lab.github.io/restic-profile/>, and local docs configuration is stored in `mkdocs.yml`.

restic_profile_cli-0.3.0/README.zh-CN.md

@@ -0,0 +1,67 @@
+# restic-profile
+
+[English](README.md) | **简体中文**
+
+[![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/ak1ra-lab/restic-profile/.github%2Fworkflows%2Fpublish-to-pypi.yaml)](https://github.com/ak1ra-lab/restic-profile/actions/workflows/publish-to-pypi.yaml)
+[![PyPI - Version](https://img.shields.io/pypi/v/restic-profile-cli)](https://pypi.org/project/restic-profile-cli/)
+[![PyPI - Version](https://img.shields.io/pypi/v/restic-profile-cli?label=test-pypi&pypiBaseUrl=https%3A%2F%2Ftest.pypi.org)](https://test.pypi.org/project/restic-profile-cli/)
+[![Docs](https://img.shields.io/badge/docs-online-0a7ea4)](https://ak1ra-lab.github.io/restic-profile/)
+
+# restic-profile
+
+基于配置文件的 restic 自动化工具，支持 Ansible 部署。
+
+包含 `restic-profile` Python CLI 以及用于 `restic-profile` 和 `restic-rest-server` 部署的 Ansible 角色。
+
+## 安装
+
+```shell
+uv sync --group dev
+```
+
+## 可选的 Ansible 工具链
+
+如需使用 Ansible 角色，可在用户级别安装工具链一次：
+
+```shell
+uv tool install ansible-dev-tools --with ansible \
+	--with-executables-from ansible-builder,ansible-core,ansible-creator,ansible-dev-environment,ansible-lint,ansible-navigator,ansible-sign,molecule
+```
+
+日常 Ansible 验证目前使用 `ansible-lint`。Molecule 场景保留在仓库中作为闲置资产，不属于支持的验证流程。
+
+如果你使用 `roles/go_build` 或 `playbooks/go_build/` 下的 playbook，控制节点还需要在 `PATH` 中有可用的 `go` 工具链。
+
+## 仓库开发流程
+
+将 collections 克隆到 `ansible_collections/ak1ra_lab/` 命名空间布局：
+
+```shell
+mkdir -p ~/code/github.com/ansible/collections/ansible_collections/ak1ra_lab
+git clone https://github.com/ak1ra-lab/ansible-collection-general.git \
+	~/code/github.com/ansible/collections/ansible_collections/ak1ra_lab/general
+git clone https://github.com/ak1ra-lab/restic-profile.git \
+	~/code/github.com/ansible/collections/ansible_collections/ak1ra_lab/restic_profile
+```
+
+## 用法
+
+```shell
+uv run restic-profile --help
+```
+
+对于 Ansible 管理的备份服务器，请参见 `restic_rest_server` 角色和 `docs/restic-rest-server/` 下的文档。
+
+## 开发
+
+```shell
+just lint
+just typecheck
+just test
+just docs-build
+ansible-lint
+```
+
+## 文档
+
+已发布的文档站点位于 <https://ak1ra-lab.github.io/restic-profile/>，本地文档配置存储在 `mkdocs.yml` 中。

{restic_profile_cli-0.2.1 → restic_profile_cli-0.3.0}/docs/index.md

@@ -63,6 +63,6 @@ and fill in your host_vars.
 | Deploy backup profiles with Ansible         | [Ansible examples](restic-profile/examples.md)        |
 | Write a TOML config for use without Ansible | [TOML config template](restic-profile/toml-config.md) |
 | Understand CLI flags                        | [CLI reference](restic-profile/cli.md)                |
-| Deploy a backup server (rest-server)        | [restic-rest-server](restic-rest-server/index.md)     |
+| Deploy a backup server (rest-server)        | [restic-rest-server](restic-rest-server.md)     |
 
 See `roles/restic_profile/defaults/main.yaml` for all role variables and their defaults.

restic_profile_cli-0.3.0/docs/index.zh.md

@@ -0,0 +1,65 @@
+# restic-profile
+
+基于配置文件的 [restic](https://restic.net/) 自动化工具 —— Python CLI + Ansible 角色。
+
+- **restic-profile** CLI：读取 TOML 配置文件，运行 `restic backup` / `forget` / `prune`，支持钩子和即时通讯通知。
+- **restic_profile** Ansible 角色：部署 CLI，渲染 TOML 配置，为每个备份配置文件管理一个 systemd 定时器。支持 `systemd_scope: user` 的用户级部署。
+- **restic_rest_server** Ansible 角色：部署 [rest-server](https://github.com/restic/rest-server) 实例，提供远程备份存储。
+
+## 安装
+
+### 独立 CLI（无需 Ansible、root 或 systemd）
+
+```shell
+uv tool install restic-profile-cli
+```
+
+然后编写配置文件 —— 可以从 [TOML 配置模板](restic-profile/toml-config.md) 开始 ——
+然后交互式运行：
+
+```shell
+restic-profile -c /path/to/my.toml --check
+restic-profile -c /path/to/my.toml myprofile
+restic-profile -c /path/to/my.toml myprofile -n
+```
+
+不涉及 systemd 定时器；你可以手动调用 CLI 或将其包装在 cron 中。
+
+### Ansible 部署
+
+本仓库是一个 Ansible 集合。将其克隆到标准命名空间布局下：
+
+```shell
+mkdir -p collections/ansible_collections/ak1ra_lab
+cd collections/ansible_collections/ak1ra_lab
+git clone https://github.com/ak1ra-lab/restic-profile.git restic_profile
+```
+
+该角色依赖 **ak1ra_lab.general.pyproject_install** 角色。将其一并安装：
+
+```shell
+cd collections/ansible_collections/ak1ra_lab
+git clone https://github.com/ak1ra-lab/ansible-collection-general.git general
+```
+
+或通过 `ansible-galaxy` 安装依赖：
+
+```shell
+ansible-galaxy collection install -r requirements.yml
+```
+
+附带的 `ansible.cfg` 要求仓库恰好位于 4 层目录深度
+（`collections/ansible_collections/ak1ra_lab/restic_profile/ansible.cfg`）。如果你的检出路径不同，请调整 `ansible.cfg` 中的 `collections_path`。
+
+现在从 [restic-profile 示例](restic-profile/examples.md) 中选择一个示例并填写你的 host_vars。
+
+## 页面
+
+| 你想...                              | 从这里开始                                            |
+| ------------------------------------------- | ----------------------------------------------------- |
+| 使用 Ansible 部署备份配置文件         | [Ansible 示例](restic-profile/examples.md)        |
+| 编写用于非 Ansible 场景的 TOML 配置 | [TOML 配置模板](restic-profile/toml-config.md) |
+| 了解 CLI 参数                        | [CLI 参考](restic-profile/cli.md)                |
+| 部署备份服务器 (rest-server)        | [restic-rest-server](restic-rest-server.md)     |
+
+参见 `roles/restic_profile/defaults/main.yaml` 了解所有角色变量及其默认值。

{restic_profile_cli-0.2.1 → restic_profile_cli-0.3.0}/docs/restic-profile/cli.md

@@ -9,7 +9,7 @@ restic-profile -U [-c PATH] [-n] PROFILE  # --unlock
 
 | Flag                       | Alias        | Purpose                                                                                             |
 | -------------------------- | ------------ | --------------------------------------------------------------------------------------------------- |
-| `--config PATH`            | `-c`         | Config file (default: `/etc/restic-profile/restic-profile.toml`)                                    |
+| `--config PATH`            | `-c`         | Config file.  When omitted, searches ``$RESTIC_PROFILE_CONFIG``, then ``$XDG_CONFIG_HOME/restic-profile/restic-profile.toml``, then ``/etc/restic-profile/restic-profile.toml`` |
 | `--check`                  | `-C`         | Parse and validate the config, then exit                                                            |
 | `--list`                   | `-l`         | Print profile table (name, type, schedule, repository)                                              |
 | `--unlock PROFILE`         | `-U`         | Remove stale restic locks for the profile's repository                                              |

restic_profile_cli-0.3.0/docs/restic-profile/cli.zh.md

@@ -0,0 +1,65 @@
+# CLI 参考
+
+```text
+restic-profile [-c PATH] [-n [{all,notify}]] PROFILE
+restic-profile -C [-c PATH]          # --check
+restic-profile -l [-c PATH]          # --list
+restic-profile -U [-c PATH] [-n] PROFILE  # --unlock
+```
+
+| 参数                       | 别名        | 说明                                                                                             |
+| -------------------------- | ------------ | --------------------------------------------------------------------------------------------------- |
+| `--config PATH`            | `-c`         | 配置文件路径。省略时依次搜索 ``$RESTIC_PROFILE_CONFIG``、``$XDG_CONFIG_HOME/restic-profile/restic-profile.toml``、``/etc/restic-profile/restic-profile.toml`` |
+| `--check`                  | `-C`         | 解析并验证配置文件，然后退出                                                            |
+| `--list`                   | `-l`         | 打印配置文件列表（名称、类型、计划、仓库）                                              |
+| `--unlock PROFILE`         | `-U`         | 为配置文件的仓库解除过期 restic 锁                                              |
+| `--dry-run [{all,notify}]` | `-n`         | `all`（默认）：仅记录日志不执行。`notify`：空运行子进程但发送真实通知 |
+| `PROFILE`                  | (位置参数) | 要执行的配置文件名                                                               |
+
+`--check`、`--list` 和 `--unlock` 互斥。不能同时使用配置文件名称与其中任何一个。
+
+```shell
+# 运行配置文件
+restic-profile myapp
+restic-profile myapp -n                    # 空运行所有
+restic-profile myapp -n notify             # 空运行 + 真实通知
+restic-profile myapp -c /path/to/custom.toml
+
+# 验证配置
+restic-profile -C
+restic-profile -C -c /path/to/custom.toml
+
+# 列出配置文件
+restic-profile -l
+
+# 解除过期锁
+restic-profile -U myapp
+restic-profile -U myapp -n
+```
+
+## Shell 补全
+
+```bash
+# bash — 添加到 ~/.bashrc
+if command -v register-python-argcomplete >/dev/null 2>&1; then
+    eval "$(register-python-argcomplete restic-profile)"
+fi
+
+# zsh — 添加到 ~/.zshrc (需要 bashcompinit)
+autoload -U +X bashcompinit && bashcompinit
+if command -v register-python-argcomplete >/dev/null 2>&1; then
+    eval "$(register-python-argcomplete restic-profile)"
+fi
+```
+
+或使用 `activate-global-python-argcomplete` 进行系统级补全：
+
+```bash
+# 按用户安装
+activate-global-python-argcomplete --user
+
+# 系统级安装
+sudo activate-global-python-argcomplete
+```
+
+这会将补全脚本写入全局位置，因此不需要 `.bashrc`/`.zshrc` 片段。

{restic_profile_cli-0.2.1 → restic_profile_cli-0.3.0}/docs/restic-profile/examples.md

@@ -271,6 +271,46 @@ cleanup is needed. Set a smaller value if disk space is tight.
 
 ---
 
+## 8. User-scope backup for an unprivileged user
+
+```yaml
+restic_profile_repositories:
+  r1:
+    repository: "rest:https://backup.example.com:8000/alice/laptop"
+    password: "{{ vault_alice_restic_password }}"
+    rest_username: "alice"
+    rest_password: "{{ vault_rest_server_alice_password }}"
+
+restic_profile_profiles:
+  alice-home:
+    repository_ref: r1
+    systemd_scope: user
+    systemd_user: alice
+    on_calendar: "daily"
+    randomized_delay_sec: "30min"
+    backup:
+      sources:
+        - /home/alice
+        - /home/alice/Documents
+      exclude_patterns:
+        - "*.tmp"
+        - ".cache/"
+    retention:
+      keep_daily: 14
+```
+
+User-scope profiles require `systemd_scope: user` and an explicit
+`systemd_user`.  The role deploys config under
+`~/.config/restic-profile/`, units under `~/.config/systemd/user/`, and
+state under `~/.local/share/restic-profile/`.  Timers start and stop
+with the user's session without requiring `root` privileges.
+
+The `restic-profile` CLI automatically resolves config from
+`~/.config/restic-profile/restic-profile.toml` when available
+(controlled by `$XDG_CONFIG_HOME` and `$RESTIC_PROFILE_CONFIG`).
+
+---
+
 ## Global role variables
 
 These affect every profile unless a profile overrides its copy.

restic_profile_cli-0.3.0/docs/restic-profile/examples.zh.md

@@ -0,0 +1,307 @@
+# Ansible host_vars 示例
+
+所有示例都是 `restic_profile` 角色的 `host_vars` 片段。每个字段都有合理的默认值 —— 完整参考和内联注释见 `roles/restic_profile/defaults/main.yaml`。
+
+```yaml
+# playbooks/restic-profile.yaml
+---
+- name: manage restic backup profiles
+  hosts: "{{ playbook_hosts | default('restic_profile_nodes') }}"
+  gather_facts: false
+  become: true
+  tasks:
+    - name: apply restic_profile role
+      ansible.builtin.import_role:
+        name: ak1ra_lab.restic_profile.restic_profile
+```
+
+---
+
+## 1. 备份到 REST 服务器的最简配置
+
+```yaml
+restic_profile_repositories:
+  r1:
+    repository: "rest:https://backup.example.com:8000/alice/laptop"
+    password: "{{ vault_laptop_restic_password }}"
+    rest_username: "alice"
+    rest_password: "{{ vault_rest_server_alice_password }}"
+
+restic_profile_profiles:
+  laptop-home:
+    repository_ref: r1
+    on_calendar: "hourly"
+    randomized_delay_sec: "15min"
+    backup:
+      sources:
+        - /home/alice
+```
+
+一个配置文件，一个定时器，无保留策略。`tag` 默认值为配置文件名称 `laptop-home`。
+
+---
+
+## 2. 备份 + 保留策略 + Telegram 通知 + 钩子
+
+```yaml
+restic_profile_notify_configs:
+  tg:
+    type: telegram
+    token: "{{ vault_telegram_bot_token }}"
+    chat_id: -1001234567890
+    env:
+      HTTPS_PROXY: "http://proxy.example.com:8080"
+      NO_PROXY: "localhost,127.0.0.1,.local"
+
+restic_profile_repositories:
+  r1:
+    repository: "rest:https://backup.example.com:8000/apps/myapp"
+    password: "{{ vault_myapp_restic_password }}"
+    rest_username: "myapp"
+    rest_password: "{{ vault_rest_server_myapp_password }}"
+
+restic_profile_profiles:
+  myapp:
+    repository_ref: r1
+    notify_ref: tg
+    on_calendar: "daily"
+    randomized_delay_sec: "30min"
+    hooks:
+      prevalidate:
+        - "test -d /srv/myapp || exit 1"
+      before:
+        - "systemctl stop myapp.service"
+      after:
+        - "systemctl start myapp.service"
+    backup:
+      sources:
+        - /srv/myapp
+        - /etc/myapp
+      exclude_patterns:
+        - "*.tmp"
+        - ".venv/"
+      exclude_file_content: |
+        __pycache__/
+        node_modules/
+    retention:
+      keep_daily: 14
+      keep_weekly: 8
+      keep_monthly: 12
+```
+
+先执行备份，然后执行内联保留策略（以本机为范围）。成功时 Telegram 会收到快照统计信息和前 N 个最大文件。
+
+在配置文件上设置 `enabled: false` 可在下次运行时停止并移除其单元。设置 `timer_enabled: false` 可部署单元但保持定时器停止状态。
+
+---
+
+## 3. 仓库主机上的纯保留策略
+
+```yaml
+restic_profile_repositories:
+  r1:
+    repository: "/srv/restic/apps/myapp"
+    password: "{{ vault_myapp_restic_password }}"
+
+restic_profile_profiles:
+  myapp-retention:
+    repository_ref: r1
+    tag: "myapp"
+    on_calendar: "daily"
+    retention:
+      forget_current_host: false
+      prune: true
+      keep_daily: 14
+      keep_weekly: 8
+      keep_monthly: 12
+```
+
+无 `backup` 块 —— 这是一个纯保留配置文件。`forget_current_host: false` 使其可以管理来自共享同一 tag 的多个备份客户端的快照。
+
+---
+
+## 4. S3 兼容后端与 PostgreSQL
+
+```yaml
+restic_profile_repositories:
+  s3:
+    repository: "s3:https://s3.example.com/backups/postgresql"
+    password: "{{ vault_postgres_restic_password }}"
+    aws_default_region: "us-east-1"
+    aws_access_key_id: "{{ vault_s3_access_key }}"
+    aws_secret_access_key: "{{ vault_s3_secret_key }}"
+
+restic_profile_profiles:
+  postgres:
+    repository_ref: s3
+    on_calendar: "03:15"
+    randomized_delay_sec: "5min"
+    env:
+      PGHOST: "{{ vault_postgres_host }}"
+      PGPORT: "{{ vault_postgres_port | default('5432') }}"
+      PGUSER: "{{ vault_postgres_user }}"
+      PGPASSWORD: "{{ vault_postgres_password }}"
+    hooks:
+      before:
+        - "mkdir -p /var/backups/postgresql"
+        - "pg_dumpall -U postgres > /var/backups/postgresql/all.sql"
+      success:
+        - "rm -f /var/backups/postgresql/all.sql"
+    backup:
+      sources:
+        - /var/backups/postgresql
+    retention:
+      keep_last: 7
+      keep_daily: 7
+      keep_weekly: 4
+```
+
+S3 端点嵌入在 `repository` URL 中（`s3:https://host/bucket`）。对于 GCS，使用 `gs:bucket-name:/prefix` 并设置 `google_project_id`。
+
+使用 `pg_dumpall` 进行完整集群导出（角色 + 所有数据库），或使用 `pg_dump <dbname>` 导出单个数据库。切勿直接备份 PostgreSQL 数据目录。
+
+---
+
+## 5. MySQL 备份
+
+```yaml
+restic_profile_repositories:
+  r1:
+    repository: "rest:https://backup.example.com:8000/apps/mysql"
+    password: "{{ vault_mysql_restic_password }}"
+    rest_username: "mysql"
+    rest_password: "{{ vault_rest_server_mysql_password }}"
+
+restic_profile_profiles:
+  mysql:
+    repository_ref: r1
+    on_calendar: "daily"
+    randomized_delay_sec: "10min"
+    env:
+      MYSQL_HOST: "{{ vault_mysql_host }}"
+      MYSQL_TCP_PORT: "{{ vault_mysql_port | default('3306') }}"
+      MYSQL_PWD: "{{ vault_mysql_root_password }}"
+    hooks:
+      before:
+        - "mkdir -p /var/backups/mysql"
+        - "mysqldump --all-databases --single-transaction -u root > /var/backups/mysql/all.sql"
+      success:
+        - "rm -f /var/backups/mysql/all.sql"
+    backup:
+      sources:
+        - /var/backups/mysql
+    retention:
+      keep_daily: 7
+```
+
+`--single-transaction` 确保 InnoDB 表在不阻塞写入的情况下获得一致性快照。对于 MyISAM，使用 `--lock-tables`。切勿直接备份 `/var/lib/mysql`。
+
+---
+
+## 6. SQLite 备份
+
+```yaml
+restic_profile_repositories:
+  r1:
+    repository: "/srv/restic/apps/sqlite"
+    password: "{{ vault_sqlite_restic_password }}"
+
+restic_profile_profiles:
+  sqlite:
+    repository_ref: r1
+    on_calendar: "daily"
+    hooks:
+      before:
+        - "mkdir -p /var/backups/sqlite"
+        - "sqlite3 /srv/myapp/data.db '.backup /var/backups/sqlite/data.db'"
+      success:
+        - "rm -f /var/backups/sqlite/data.db"
+    backup:
+      sources:
+        - /var/backups/sqlite
+    retention:
+      keep_daily: 7
+```
+
+SQLite 的 `.backup` 命令使用在线备份 API 创建一致性快照。避免在使用中直接复制数据库文件。
+
+---
+
+## 7. GitLab 备份
+
+```yaml
+restic_profile_repositories:
+  r1:
+    repository: "rest:https://backup.example.com:8000/apps/gitlab"
+    password: "{{ vault_gitlab_restic_password }}"
+
+restic_profile_profiles:
+  gitlab:
+    repository_ref: r1
+    on_calendar: "daily"
+    randomized_delay_sec: "15min"
+    hooks:
+      before:
+        - "/usr/bin/gitlab-rake gitlab:backup:create"
+    backup:
+      sources:
+        - /var/opt/gitlab/backups
+    retention:
+      keep_daily: 7
+      keep_weekly: 4
+```
+
+`gitlab:backup:create` 将带时间戳的 tar 包写入 `/var/opt/gitlab/backups`。GitLab 内置的 `gitlab_rails['backup_keep_time']`（默认 `604800` —— `/etc/gitlab/gitlab.rb` 中为 7 天）会自动清理旧的本地归档文件，因此无需手动清理。如果磁盘空间紧张，可设置较小的值。
+
+---
+
+## 8. 非特权用户的 user-scope 备份
+
+```yaml
+restic_profile_repositories:
+  r1:
+    repository: "rest:https://backup.example.com:8000/alice/laptop"
+    password: "{{ vault_alice_restic_password }}"
+    rest_username: "alice"
+    rest_password: "{{ vault_rest_server_alice_password }}"
+
+restic_profile_profiles:
+  alice-home:
+    repository_ref: r1
+    systemd_scope: user
+    systemd_user: alice
+    on_calendar: "daily"
+    randomized_delay_sec: "30min"
+    backup:
+      sources:
+        - /home/alice
+        - /home/alice/Documents
+      exclude_patterns:
+        - "*.tmp"
+        - ".cache/"
+    retention:
+      keep_daily: 14
+```
+
+User-scope 配置文件需要 `systemd_scope: user` 和显式的 `systemd_user`。角色将配置部署在 `~/.config/restic-profile/` 下，单元部署在 `~/.config/systemd/user/` 下，状态部署在 `~/.local/share/restic-profile/` 下。定时器随用户会话启动和停止，无需 `root` 权限。
+
+`restic-profile` CLI 在可用时自动从 `~/.config/restic-profile/restic-profile.toml` 解析配置（由 `$XDG_CONFIG_HOME` 和 `$RESTIC_PROFILE_CONFIG` 控制）。
+
+---
+
+## 全局角色变量
+
+以下变量影响所有配置文件，除非配置文件单独覆盖。
+
+| 变量                               | 默认值   | 含义                                                      |
+| -------------------------------------- | --------- | ------------------------------------------------------------ |
+| `restic_profile_state`                 | `present` | 设置为 `absent` 以停止定时器并移除所有受管理文件     |
+| `restic_profile_restic_binary`         | `""`      | 从 PATH 解析；设置为指定特定的二进制文件             |
+| `restic_profile_no_cache`              | `false`   | 为每个 restic 调用添加 `--no-cache`                  |
+| `restic_profile_retry_lock`            | `""`      | `--retry-lock` 持续时间（与旧版 restic ≤0.14 不兼容） |
+| `restic_profile_unlock`                | `false`   | 在每个备份/保留操作之前运行 `restic unlock`            |
+| `restic_profile_systemd_cpu_quota`     | `"100%"`  | 生成的 service 单元中的 CPUQuota=                         |
+| `restic_profile_pip_install_source`    | `local`   | 如何安装 restic-profile：`local` / `pypi` / `testpypi` |
+| `restic_profile_restic_install_source` | `apt`     | 如何安装 restic：`apt` / `go_build` / `existing`       |
+
+完整列表和注释见 `roles/restic_profile/defaults/main.yaml`。

{restic_profile_cli-0.2.1 → restic_profile_cli-0.3.0}/docs/restic-profile/toml-config.md

@@ -1,7 +1,8 @@
 ```toml
 # restic-profile.toml — well-commented starting config
 #
-# Copy this file to /etc/restic-profile/restic-profile.toml, fill in your
+# Copy this file to /etc/restic-profile/restic-profile.toml (system scope)
+# or ~/.config/restic-profile/restic-profile.toml (user scope), fill in your
 # credentials and paths, then run:
 #   restic-profile --check           # validate the config
 #   restic-profile --list            # list all profiles