docs: add Notification section documentation
This commit is contained in:
@@ -14,20 +14,6 @@ Docker containers for [vaultwarden](https://github.com/dani-garcia/vaultwarden)
|
||||
|
||||
|
||||
|
||||
## Rename
|
||||
|
||||
**Unofficial Bitwarden compatible server written in Rust, formerly known as `bitwarden_rs`, renamed to `vaultwarden`.**
|
||||
|
||||
For this reason, the backup tool was migrated to [ttionya/vaultwarden-backup](https://github.com/ttionya/vaultwarden-backup).
|
||||
|
||||
The old image can still be used, just **DEPRECATED**. It is recommended to migrate to new image [ttionya/vaultwarden-backup](https://hub.docker.com/r/ttionya/vaultwarden-backup).
|
||||
|
||||
**See how to migrate [here](#migration).**
|
||||
|
||||
<br>
|
||||
|
||||
|
||||
|
||||
## Feature
|
||||
|
||||
This tool supports backing up the following files or directories.
|
||||
@@ -328,68 +314,6 @@ Here is timezone list at [wikipedia](https://en.wikipedia.org/wiki/List_of_tz_da
|
||||
|
||||
Default: `UTC`
|
||||
|
||||
#### PING_URL
|
||||
|
||||
Use [healthcheck.io](https://healthchecks.io/) url or similar cron monitoring to perform `GET` requests after a backup **no matter if it succeeds or fails**.
|
||||
|
||||
#### PING_URL_WHEN_START
|
||||
|
||||
Use [healthcheck.io](https://healthchecks.io/) url or similar cron monitoring to perform `GET` requests at the **beginning** of a backup.
|
||||
|
||||
#### PING_URL_WHEN_SUCCESS
|
||||
|
||||
Use [healthcheck.io](https://healthchecks.io/) url or similar cron monitoring to perform `GET` requests after a **successful** backup.
|
||||
|
||||
#### PING_URL_WHEN_FAILURE
|
||||
|
||||
Use [healthcheck.io](https://healthchecks.io/) url or similar cron monitoring to perform `GET` requests after a backup **fails**.
|
||||
|
||||
#### MAIL_SMTP_ENABLE
|
||||
|
||||
Starting from v1.19.0, we will be using [`s-nail`](https://www.sdaoden.eu/code-nail.html) instead of [`heirloom-mailx`](https://www.systutorials.com/docs/linux/man/1-heirloom-mailx/) to send emails.
|
||||
|
||||
Please note that `heirloom-mailx` is a stub for `s-nail`, and most of its functionality is compatible. Therefore, you may not need to modify any environment variables for this change.
|
||||
|
||||
Default: `FALSE`
|
||||
|
||||
#### MAIL_SMTP_VARIABLES
|
||||
|
||||
Because the configuration for sending emails is too complicated, we allow you to configure it yourself.
|
||||
|
||||
**We will set the subject according to the usage scenario, so you should not use the `-s` option.**
|
||||
|
||||
During testing, we will add the `-v` option to display detailed information.
|
||||
|
||||
```text
|
||||
# My example:
|
||||
|
||||
# For Zoho
|
||||
-S smtp-use-starttls \
|
||||
-S smtp=smtp://smtp.zoho.com:587 \
|
||||
-S smtp-auth=login \
|
||||
-S smtp-auth-user=<my-email-address> \
|
||||
-S smtp-auth-password=<my-email-password> \
|
||||
-S from=<my-email-address>
|
||||
```
|
||||
|
||||
Console showing warnings? Check [issue #177](https://github.com/ttionya/vaultwarden-backup/issues/117#issuecomment-1691443179) for more details.
|
||||
|
||||
#### MAIL_TO
|
||||
|
||||
This specifies the recipient of the notification email.
|
||||
|
||||
#### MAIL_WHEN_SUCCESS
|
||||
|
||||
Sends an email when the backup is successful.
|
||||
|
||||
Default: `TRUE`
|
||||
|
||||
#### MAIL_WHEN_FAILURE
|
||||
|
||||
Sends an email when the backup fails.
|
||||
|
||||
Default: `TRUE`
|
||||
|
||||
#### DATA_DIR
|
||||
|
||||
This folder stores the data of vaultwarden.
|
||||
@@ -398,6 +322,8 @@ When using `Docker Compose`, this does not need to be changed. However, when usi
|
||||
|
||||
Default: `/bitwarden/data`
|
||||
|
||||
※ Please refer to the [`Notification`](#notification) section for notification-related environment variables.
|
||||
|
||||
<details>
|
||||
<summary><strong>※ Other environment variables</strong></summary>
|
||||
|
||||
@@ -456,45 +382,45 @@ Default: `${DATA_DIR}/sends`
|
||||
|
||||
|
||||
|
||||
## Using `.env` file
|
||||
## Notification
|
||||
|
||||
If you prefer using an env file instead of environment variables, you can map the env file containing the environment variables to the `/.env` file in the container.
|
||||
### Mail
|
||||
|
||||
```shell
|
||||
docker run -d \
|
||||
--mount type=bind,source=/path/to/env,target=/.env \
|
||||
ttionya/vaultwarden-backup:latest
|
||||
Starting from v1.19.0, we will be using [`s-nail`](https://www.sdaoden.eu/code-nail.html) instead of [`heirloom-mailx`](https://www.systutorials.com/docs/linux/man/1-heirloom-mailx/) to send emails.
|
||||
|
||||
Please note that `heirloom-mailx` is a stub for `s-nail`, and most of its functionality is compatible. Therefore, you may not need to modify any environment variables for this change.
|
||||
|
||||
| Environment Variable | Default Value | Description |
|
||||
| --- | --- |-------------------------------------------------------|
|
||||
| MAIL_SMTP_ENABLE | `FALSE` | Enable sending mail. |
|
||||
| MAIL_SMTP_VARIABLES | | Mail sending options. |
|
||||
| MAIL_TO | | The recipient of the notification email. |
|
||||
| MAIL_WHEN_SUCCESS | `TRUE` | Send an email when the backup completes successfully. |
|
||||
| MAIL_WHEN_FAILURE | `TRUE` | Send an email if the backup fails. |
|
||||
|
||||
For `MAIL_SMTP_VARIABLES`, you need to configure the mail sending options yourself. **We will set the email subject based on the usage scenario, so you should not use the `-s` flag.**
|
||||
|
||||
```text
|
||||
# My example:
|
||||
|
||||
# For Zoho
|
||||
-S smtp-use-starttls \
|
||||
-S smtp=smtp://smtp.zoho.com:587 \
|
||||
-S smtp-auth=login \
|
||||
-S smtp-auth-user=<my-email-address> \
|
||||
-S smtp-auth-password=<my-email-password> \
|
||||
-S from=<my-email-address>
|
||||
```
|
||||
|
||||
<br>
|
||||
|
||||
|
||||
|
||||
## Docker Secrets
|
||||
|
||||
As an alternative to passing sensitive information via environment variables, `_FILE` may be appended to the previously listed environment variables. This causes the initialization script to load the values for those variables from files present in the container. In particular, this can be used to load passwords from Docker secrets stored in `/run/secrets/<secret_name>` files.
|
||||
|
||||
```shell
|
||||
docker run -d \
|
||||
-e ZIP_PASSWORD_FILE=/run/secrets/zip-password \
|
||||
ttionya/vaultwarden-backup:latest
|
||||
```
|
||||
Console showing warnings? Check [issue #177](https://github.com/ttionya/vaultwarden-backup/issues/117#issuecomment-1691443179) for more details.
|
||||
|
||||
<br>
|
||||
|
||||
|
||||
|
||||
## About Priority
|
||||
### Mail Test
|
||||
|
||||
We will use the environment variables first, followed by the contents of the file ending in `_FILE` as defined by the environment variables. Next, we will use the contents of the file ending in `_FILE` as defined in the `.env` file, and finally the values from the `.env` file itself.
|
||||
|
||||
<br>
|
||||
|
||||
|
||||
|
||||
## Mail Test
|
||||
|
||||
You can use the following command to test mail sending. Remember to replace your SMTP variables.
|
||||
You can use the following command to test mail sending. We will add the `-v` flag to display detailed information, so you do not need to set it again in `MAIL_SMTP_VARIABLES`.
|
||||
|
||||
```shell
|
||||
docker run --rm -it -e MAIL_SMTP_VARIABLES='<your smtp variables>' ttionya/vaultwarden-backup:latest mail <mail send to>
|
||||
@@ -508,13 +434,122 @@ docker run --rm -it -e MAIL_SMTP_VARIABLES='<your smtp variables>' -e MAIL_TO='<
|
||||
|
||||
|
||||
|
||||
### Ping
|
||||
|
||||
We provide functionality to send notifications when the backup is completed, started, successful, or failed.
|
||||
|
||||
**Using a [healthcheck.io](https://healthchecks.io/) address or other similar cron monitoring addresses is a good choice, and it is also recommended.** For more complex notification scenarios, you can use environment variables with the `_CURL_OPTIONS` suffix to set curl options. For example, you can add request headers, change the request method, etc.
|
||||
|
||||
For different notification scenarios, **the backup tool provides `%{subject}` and `%{content}` placeholders to replace the actual title and content**. You can use them in the following environment variables. Note that the title and content may contain spaces. For the four environment variables containing `_CURL_OPTIONS`, the placeholders will be directly replaced, retaining spaces. For other `PING_URL` environment variables, spaces will be replaced with `+` to comply with URL rules.
|
||||
|
||||
| Environment Variable | Trigger Status | Test Identifier | Description |
|
||||
|------------------------------------|-------------|--------------|----------------------------------------------------------------------|
|
||||
| PING_URL | completion (success or failure) | `completion` | The URL to which the request is sent after the backup is completed. |
|
||||
| PING_URL_CURL_OPTIONS | | | Curl options used with `PING_URL` |
|
||||
| PING_URL_WHEN_START | start | `start` | The URL to which the request is sent when the backup starts. |
|
||||
| PING_URL_WHEN_START_CURL_OPTIONS | | | Curl options used with `PING_URL_WHEN_START` |
|
||||
| PING_URL_WHEN_SUCCESS | success | `success` | The URL to which the request is sent after the backup is successful. |
|
||||
| PING_URL_WHEN_SUCCESS_CURL_OPTIONS | | | Curl options used with `PING_URL_WHEN_SUCCESS` |
|
||||
| PING_URL_WHEN_FAILURE | failure | `failure` | The URL to which the request is sent after the backup fails. |
|
||||
| PING_URL_WHEN_FAILURE_CURL_OPTIONS | | | Curl options used with `PING_URL_WHEN_FAILURE` |
|
||||
|
||||
<br>
|
||||
|
||||
|
||||
|
||||
### Ping Test
|
||||
|
||||
You can use the following command to test the Ping function.
|
||||
|
||||
The "test identifier" is the identifier in the table in the [previous section](#ping). You can use `completion`, `start`, `success`, or `failure`, which determines which set of environment variables to use.
|
||||
|
||||
```shell
|
||||
docker run --rm -it \
|
||||
-e PING_URL='<your ping url>' -e PING_URL_CURL_OPTIONS='<your curl options for PING_URL>' \
|
||||
-e PING_URL_WHEN_START='<your ping url>' -e PING_URL_WHEN_START_CURL_OPTIONS='<your curl options for PING_URL_WHEN_START>' \
|
||||
-e PING_URL_WHEN_SUCCESS='<your ping url>' -e PING_URL_WHEN_SUCCESS_CURL_OPTIONS='<your curl options for PING_URL_WHEN_SUCCESS>' \
|
||||
-e PING_URL_WHEN_FAILURE='<your ping url>' -e PING_URL_WHEN_FAILURE_CURL_OPTIONS='<your curl options for PING_URL_WHEN_FAILURE>' \
|
||||
ttionya/vaultwarden-backup:latest ping <test identifier>
|
||||
```
|
||||
|
||||
<br>
|
||||
|
||||
|
||||
|
||||
## Environment Variables Considerations
|
||||
|
||||
### Using `.env` file
|
||||
|
||||
If you prefer using an env file instead of environment variables, you can map the env file containing the environment variables to the `/.env` file in the container.
|
||||
|
||||
```shell
|
||||
docker run -d \
|
||||
--mount type=bind,source=/path/to/env,target=/.env \
|
||||
ttionya/vaultwarden-backup:latest
|
||||
```
|
||||
|
||||
**Please do not use the `--env-file` flag directly**; make sure to map the environment variables by mounting the file. The `--env-file` flag incorrectly handles quotes, which can lead to unexpected situations. For more information, please see [docker/cli#3630](https://github.com/docker/cli/issues/3630).
|
||||
|
||||
<br>
|
||||
|
||||
|
||||
|
||||
### Docker Secrets
|
||||
|
||||
As an alternative to passing sensitive information via environment variables, you can append `_FILE` to the previously listed environment variables. This causes the initialization script to load the values for those variables from files present in the container. In particular, this can be used to load passwords from Docker secrets stored in `/run/secrets/<secret_name>` files.
|
||||
|
||||
```shell
|
||||
docker run -d \
|
||||
-e ZIP_PASSWORD_FILE=/run/secrets/zip-password \
|
||||
ttionya/vaultwarden-backup:latest
|
||||
```
|
||||
|
||||
<br>
|
||||
|
||||
|
||||
|
||||
### About Priority
|
||||
|
||||
We look for environment variables in the following order:
|
||||
|
||||
1. Directly read the value of the environment variable
|
||||
2. Read the content of the file pointed to by the environment variable ending in `_FILE`
|
||||
3. Read the content of the file pointed to by the environment variable ending in `_FILE` in the `.env` file
|
||||
4. Read the value of the environment variable in the `.env` file
|
||||
|
||||
Example:
|
||||
|
||||
```txt
|
||||
# For 1
|
||||
MY_ENV="example1"
|
||||
|
||||
# For 2
|
||||
MY_ENV_FILE="/path/to/example2"
|
||||
|
||||
# For 3 (.env file)
|
||||
MY_ENV_FILE: "/path/to/example3"
|
||||
|
||||
# For 4 (.env file)
|
||||
MY_ENV: "example4"
|
||||
```
|
||||
|
||||
<br>
|
||||
|
||||
|
||||
|
||||
## Migration
|
||||
|
||||
If you use automatic backups, you just need to replace the image with `ttionya/vaultwarden-backup`. Note the name of your volume.
|
||||
**Unofficial Bitwarden compatible server written in Rust, formerly known as `bitwarden_rs`, has been renamed to `vaultwarden`. Consequently, this backup tool has also been renamed from `bitwardenrs-backup` to `vaultwarden-backup`.**
|
||||
|
||||
If you are using `docker-compose`, you need to update `bitwardenrs/server` to `vaultwarden/server` and `ttionya/bitwardenrs-backup` to `ttionya/vaultwarden-backup`.
|
||||
The old image can still be used, just **DEPRECATED**. Please migrate to the new image as soon as possible.
|
||||
|
||||
We recommend re-downloading the `docker-compose.yml` file, replacing your environment variables, and noting the `volumes` section, which you may need to change.
|
||||
Please follow the instructions below to migrate:
|
||||
|
||||
If you use automatic backups, you only need to replace the image with `ttionya/vaultwarden-backup`. Note the name of your volume.
|
||||
|
||||
If you use `docker-compose`, you need to update `bitwardenrs/server` to `vaultwarden/server` and `ttionya/bitwardenrs-backup` to `ttionya/vaultwarden-backup`.
|
||||
|
||||
We recommend re-downloading the [`docker-compose.yml`](./docker-compose.yml) file, updating your environment variables, and paying attention to the `volumes` section, which you may need to modify.
|
||||
|
||||
<br>
|
||||
|
||||
@@ -544,7 +579,7 @@ Check out the [CHANGELOG](CHANGELOG.md) file.
|
||||
|
||||
I am grateful for the OSS license provided by [JetBrains](https://www.jetbrains.com/).
|
||||
|
||||
<a href="https://jb.gg/OpenSourceSupport" target="_blank"><img src="https://resources.jetbrains.com/storage/products/company/brand/logos/jb_beam.png" alt="JetBrains Logo (Main) logo" width="300"></a>
|
||||
<a href="https://jb.gg/OpenSourceSupport" target="_blank"><img src="https://resources.jetbrains.com/storage/products/company/brand/logos/jb_beam.png" alt="JetBrains Logo (Main) logo" width="200"></a>
|
||||
|
||||
<br>
|
||||
|
||||
|
||||
+142
-107
@@ -14,20 +14,6 @@
|
||||
|
||||
|
||||
|
||||
## 重命名
|
||||
|
||||
**用 Rust 编写的非官方 Bitwarden 服务器,以前称为 `bitwarden_rs`,现在已经改名为 `vaultwarden`。**
|
||||
|
||||
所以这个备份工具迁移到了 [ttionya/vaultwarden-backup](https://github.com/ttionya/vaultwarden-backup) 。
|
||||
|
||||
旧的镜像仍然可以使用,只是 **DEPRECATED** 了。建议迁移到新的镜像 [ttionya/vaultwarden-backup](https://hub.docker.com/r/ttionya/vaultwarden-backup) 。
|
||||
|
||||
**请在[这里](#迁移)查看如何迁移**。
|
||||
|
||||
<br>
|
||||
|
||||
|
||||
|
||||
## 功能
|
||||
|
||||
本工具会备份以下文件或目录。
|
||||
@@ -326,68 +312,6 @@ Rclone 全局参数,详见 [flags](https://rclone.org/flags/)。
|
||||
|
||||
默认值:`UTC`
|
||||
|
||||
#### PING_URL
|
||||
|
||||
使用 [healthcheck.io](https://healthchecks.io/) 地址或者其他类似的 cron 监控,以便在备份**完成(不论成功或失败)**后执行 `GET` 请求。
|
||||
|
||||
#### PING_URL_WHEN_START
|
||||
|
||||
使用 [healthcheck.io](https://healthchecks.io/) 地址或者其他类似的 cron 监控,以便在备份**开始**前执行 `GET` 请求。
|
||||
|
||||
#### PING_URL_WHEN_SUCCESS
|
||||
|
||||
使用 [healthcheck.io](https://healthchecks.io/) 地址或者其他类似的 cron 监控,以便在备份**成功**后执行 `GET` 请求。
|
||||
|
||||
#### PING_URL_WHEN_FAILURE
|
||||
|
||||
使用 [healthcheck.io](https://healthchecks.io/) 地址或者其他类似的 cron 监控,以便在备份**失败**后执行 `GET` 请求。
|
||||
|
||||
#### MAIL_SMTP_ENABLE
|
||||
|
||||
从 v1.19.0 开始,本工具使用 [`s-nail`](https://www.sdaoden.eu/code-nail.html) 代替 [`heirloom-mailx`](https://www.systutorials.com/docs/linux/man/1-heirloom-mailx/) 发送邮件。
|
||||
|
||||
请注意,`heirloom-mailx` 是 `s-nail` 的基础,它们大部分功能是兼容的。因此你可能不需要为这个改变修改任何环境变量。
|
||||
|
||||
默认值:`FALSE`
|
||||
|
||||
#### MAIL_SMTP_VARIABLES
|
||||
|
||||
因为发送邮件的配置太复杂,请自己配置邮件发送参数。
|
||||
|
||||
**我们会根据使用场景设置邮件主题,所以你不应该使用 `-s` 选项。**
|
||||
|
||||
测试期间,我们将增加 `-v` 选项来显示详细信息。
|
||||
|
||||
```text
|
||||
# 提供一个能正常使用的例子:
|
||||
|
||||
# For Zoho
|
||||
-S smtp-use-starttls \
|
||||
-S smtp=smtp://smtp.zoho.com:587 \
|
||||
-S smtp-auth=login \
|
||||
-S smtp-auth-user=<my-email-address> \
|
||||
-S smtp-auth-password=<my-email-password> \
|
||||
-S from=<my-email-address>
|
||||
```
|
||||
|
||||
控制台有警告?查看 [issue #177](https://github.com/ttionya/vaultwarden-backup/issues/117#issuecomment-1691443179) 了解更多。
|
||||
|
||||
#### MAIL_TO
|
||||
|
||||
指定通知邮件的接收者。
|
||||
|
||||
#### MAIL_WHEN_SUCCESS
|
||||
|
||||
备份成功后发送邮件。
|
||||
|
||||
默认值:`TRUE`
|
||||
|
||||
#### MAIL_WHEN_FAILURE
|
||||
|
||||
备份失败时发送邮件。
|
||||
|
||||
默认值:`TRUE`
|
||||
|
||||
#### DATA_DIR
|
||||
|
||||
指定存放 vaultwarden 数据的目录。
|
||||
@@ -396,6 +320,8 @@ Rclone 全局参数,详见 [flags](https://rclone.org/flags/)。
|
||||
|
||||
默认值:`/bitwarden/data`
|
||||
|
||||
※ 通知相关环境变量请查看[通知](#通知)部分。
|
||||
|
||||
<details>
|
||||
<summary><strong>※ 其他环境变量</strong></summary>
|
||||
|
||||
@@ -453,45 +379,45 @@ Default: `%Y%m%d`
|
||||
|
||||
|
||||
|
||||
## Use `.env` file
|
||||
## 通知
|
||||
|
||||
如果你喜欢使用 env 文件而不是环境变量,可以将包含环境变量的 env 文件映射到容器中的 `/.env` 文件。
|
||||
### Mail
|
||||
|
||||
```shell
|
||||
docker run -d \
|
||||
--mount type=bind,source=/path/to/env,target=/.env \
|
||||
ttionya/vaultwarden-backup:latest
|
||||
从 v1.19.0 开始,本工具使用 [`s-nail`](https://www.sdaoden.eu/code-nail.html) 代替 [`heirloom-mailx`](https://www.systutorials.com/docs/linux/man/1-heirloom-mailx/) 发送邮件。
|
||||
|
||||
请注意,`heirloom-mailx` 是 `s-nail` 的存根,它们大部分功能是兼容的。因此你可能不需要为这个改变修改任何环境变量。
|
||||
|
||||
| 环境变量 | 默认值 | 描述 |
|
||||
| --- |--------|-----------|
|
||||
| MAIL_SMTP_ENABLE | `FALSE` | 启用邮件发送功能 |
|
||||
| MAIL_SMTP_VARIABLES | | 邮件发送参数 |
|
||||
| MAIL_TO | | 接收邮件的地址 |
|
||||
| MAIL_WHEN_SUCCESS | `TRUE` | 备份成功后发送邮件 |
|
||||
| MAIL_WHEN_FAILURE | `TRUE` | 备份失败后发送邮件 |
|
||||
|
||||
对于 `MAIL_SMTP_VARIABLES`,你需要自行配置邮件发送参数。**我们会根据使用场景设置邮件主题,所以你不应该使用 `-s` 标志。**
|
||||
|
||||
```text
|
||||
# 提供一个能正常使用的例子:
|
||||
|
||||
# For Zoho
|
||||
-S smtp-use-starttls \
|
||||
-S smtp=smtp://smtp.zoho.com:587 \
|
||||
-S smtp-auth=login \
|
||||
-S smtp-auth-user=<my-email-address> \
|
||||
-S smtp-auth-password=<my-email-password> \
|
||||
-S from=<my-email-address>
|
||||
```
|
||||
|
||||
<br>
|
||||
|
||||
|
||||
|
||||
## Docker Secrets
|
||||
|
||||
作为通过环境变量传递敏感信息的替代方法,`_FILE` 可以追加到前面列出的环境变量后面,使初始化脚本从容器中存在的文件加载这些变量的值。特别是这可以用来从存储在 `/run/secrets/<secret_name>` 文件中的 Docker Secrets 中加载密码。
|
||||
|
||||
```shell
|
||||
docker run -d \
|
||||
-e ZIP_PASSWORD_FILE=/run/secrets/zip-password \
|
||||
ttionya/vaultwarden-backup:latest
|
||||
```
|
||||
控制台有警告?查看 [issue #177](https://github.com/ttionya/vaultwarden-backup/issues/117#issuecomment-1691443179) 了解更多。
|
||||
|
||||
<br>
|
||||
|
||||
|
||||
|
||||
## 关于优先级
|
||||
### 邮件发送测试
|
||||
|
||||
我们会优先使用环境变量,然后是环境变量定义的 `_FILE` 结尾的文件内容,之后是 `.env` 文件中定义的 `_FILE` 结尾的文件内容,最后才是 `.env` 文件的值。
|
||||
|
||||
<br>
|
||||
|
||||
|
||||
|
||||
## 邮件发送测试
|
||||
|
||||
你可以使用下面的命令来测试邮件的发送。记得替换你的 SMTP 变量。
|
||||
你可以使用下面的命令测试邮件发送功能。我们会增加 `-v` 标志以显示详细信息,你无需在 `MAIL_SMTP_VARIABLES` 中重复设置。
|
||||
|
||||
```shell
|
||||
docker run --rm -it -e MAIL_SMTP_VARIABLES='<your smtp variables>' ttionya/vaultwarden-backup:latest mail <mail send to>
|
||||
@@ -505,13 +431,122 @@ docker run --rm -it -e MAIL_SMTP_VARIABLES='<your smtp variables>' -e MAIL_TO='<
|
||||
|
||||
|
||||
|
||||
### Ping
|
||||
|
||||
我们提供了在备份完成、开始、成功、失败时发送通知的功能。
|
||||
|
||||
**搭配 [healthcheck.io](https://healthchecks.io/) 地址或者其他类似的 cron 监控地址是一个不错的选择,这也是我们推荐的。** 对于一些更复杂的通知场景,你可以使用 `_CURL_OPTIONS` 后缀的环境变量来设置 curl 选项。比如你可以添加请求头,改变请求方法等。
|
||||
|
||||
对于不同的通知场景,**备份工具提供了 `%{subject}` 和 `%{content}` 占位符用于替换实际的标题和内容**,你可以在以下环境变量中随意使用它们。请注意,标题和内容可能包含空格。对于包含 `_CURL_OPTIONS` 的四个环境变量,将直接替换占位符,保留空格。对于其他 `PING_URL` 环境变量,空格将被替换为 `+`,以符合 URL 规则。
|
||||
|
||||
| 环境变量 | 触发状态 | 测试标识 | 描述 |
|
||||
|------------------------------------|-------------|--------------|-----------------------------------------|
|
||||
| PING_URL | 完成(不论成功或失败) | `completion` | 备份完成后发送请求的地址 |
|
||||
| PING_URL_CURL_OPTIONS | | | 与 `PING_URL` 搭配使用的 curl 选项 |
|
||||
| PING_URL_WHEN_START | 开始 | `start` | 备份开始时发送请求的地址 |
|
||||
| PING_URL_WHEN_START_CURL_OPTIONS | | | 与 `PING_URL_WHEN_START` 搭配使用的 curl 选项 |
|
||||
| PING_URL_WHEN_SUCCESS | 成功 | `success` | 备份成功后发送请求的地址 |
|
||||
| PING_URL_WHEN_SUCCESS_CURL_OPTIONS | | | 与 `PING_URL_WHEN_SUCCESS` 搭配使用的 curl 选项 |
|
||||
| PING_URL_WHEN_FAILURE | 失败 | `failure` | 备份失败后发送请求的地址 |
|
||||
| PING_URL_WHEN_FAILURE_CURL_OPTIONS | | | 与 `PING_URL_WHEN_FAILURE` 搭配使用的 curl 选项 |
|
||||
|
||||
<br>
|
||||
|
||||
|
||||
|
||||
### Ping 测试
|
||||
|
||||
你可以使用下面的命令测试 Ping 功能。
|
||||
|
||||
“测试标识”是[上一节](#ping)表格中的标识,你可以使用 `completion`、`start`、`success` 或 `failure`,它决定了使用哪一组环境变量。
|
||||
|
||||
```shell
|
||||
docker run --rm -it \
|
||||
-e PING_URL='<your ping url>' -e PING_URL_CURL_OPTIONS='<your curl options for PING_URL>' \
|
||||
-e PING_URL_WHEN_START='<your ping url>' -e PING_URL_WHEN_START_CURL_OPTIONS='<your curl options for PING_URL_WHEN_START>' \
|
||||
-e PING_URL_WHEN_SUCCESS='<your ping url>' -e PING_URL_WHEN_SUCCESS_CURL_OPTIONS='<your curl options for PING_URL_WHEN_SUCCESS>' \
|
||||
-e PING_URL_WHEN_FAILURE='<your ping url>' -e PING_URL_WHEN_FAILURE_CURL_OPTIONS='<your curl options for PING_URL_WHEN_FAILURE>' \
|
||||
ttionya/vaultwarden-backup:latest ping <测试标识>
|
||||
```
|
||||
|
||||
<br>
|
||||
|
||||
|
||||
|
||||
## 环境变量注意事项
|
||||
|
||||
### 使用 `.env` 文件
|
||||
|
||||
如果你喜欢使用 env 文件而不是环境变量,可以将包含环境变量的 env 文件映射到容器中的 `/.env` 文件。
|
||||
|
||||
```shell
|
||||
docker run -d \
|
||||
--mount type=bind,source=/path/to/env,target=/.env \
|
||||
ttionya/vaultwarden-backup:latest
|
||||
```
|
||||
|
||||
请不要直接使用 `--env-file` 标志,务必通过挂载文件的方式映射环境变量。`--env-file` 标志会错误地处理引号,导致发生意外情况。更多信息请参见 [docker/cli#3630](https://github.com/docker/cli/issues/3630)。
|
||||
|
||||
<br>
|
||||
|
||||
|
||||
|
||||
### Docker Secrets
|
||||
|
||||
作为通过环境变量传递敏感信息的替代方法,可以在前面列出的环境变量后面追加 `_FILE`,使初始化脚本从容器中存在的文件加载这些变量的值。特别是这可以用来从存储在 `/run/secrets/<secret_name>` 文件中的 Docker Secrets 中加载密码。
|
||||
|
||||
```shell
|
||||
docker run -d \
|
||||
-e ZIP_PASSWORD_FILE=/run/secrets/zip-password \
|
||||
ttionya/vaultwarden-backup:latest
|
||||
```
|
||||
|
||||
<br>
|
||||
|
||||
|
||||
|
||||
### 关于优先级
|
||||
|
||||
我们按以下顺序查找环境变量:
|
||||
|
||||
1. 直接读取环境变量的值
|
||||
2. 读取以 `_FILE` 结尾的环境变量指向的文件的内容
|
||||
3. 读取 `.env` 文件中以 `_FILE` 结尾的环境变量指向的文件的内容
|
||||
4. 读取 `.env` 文件中环境变量的值
|
||||
|
||||
示例:
|
||||
|
||||
```txt
|
||||
# 对于 1
|
||||
MY_ENV="example1"
|
||||
|
||||
# 对于 2
|
||||
MY_ENV_FILE="/path/to/example2"
|
||||
|
||||
# 对于 3 (.env 文件)
|
||||
MY_ENV_FILE: "/path/to/example3"
|
||||
|
||||
# 对于 4 (.env 文件)
|
||||
MY_ENV: "example4"
|
||||
```
|
||||
|
||||
<br>
|
||||
|
||||
|
||||
|
||||
## 迁移
|
||||
|
||||
**用 Rust 编写的非官方 Bitwarden 服务器,以前称为 `bitwarden_rs`,已经改名为 `vaultwarden`。所以这个备份工具也由 `bitwardenrs-backup` 重命名为 `vaultwarden-backup`。**
|
||||
|
||||
旧的镜像仍然可以使用,只是被标记为 **DEPRECATED** 了,请尽快迁移到新的镜像。
|
||||
|
||||
请根据以下说明进行迁移:
|
||||
|
||||
如果你使用自动备份,你只需要把镜像名改为 `ttionya/vaultwarden-backup`。注意你的卷的名称。
|
||||
|
||||
如果你使用 `docker-compose`,你需要将 `bitwardenrs/server` 更新为 `vaultwarden/server`,`ttionya/bitwardenrs-backup` 更新为 `ttionya/vaultwarden-backup`。
|
||||
|
||||
我们建议重新下载 `docker-compose.yml` 文件,替换你的环境变量,并注意 `volumes` 一节,你可能需要改变它。
|
||||
我们建议重新下载 [`docker-compose.yml`](./docker-compose.yml) 文件,更新你的环境变量,并注意 `volumes` 部分,你可能需要修改它。
|
||||
|
||||
<br>
|
||||
|
||||
@@ -541,7 +576,7 @@ docker run --rm -it -e MAIL_SMTP_VARIABLES='<your smtp variables>' -e MAIL_TO='<
|
||||
|
||||
感谢 [JetBrains](https://www.jetbrains.com/) 提供的 OSS 许可证。
|
||||
|
||||
<a href="https://jb.gg/OpenSourceSupport" target="_blank"><img src="https://resources.jetbrains.com/storage/products/company/brand/logos/jb_beam.png" alt="JetBrains Logo (Main) logo" width="300"></a>
|
||||
<a href="https://jb.gg/OpenSourceSupport" target="_blank"><img src="https://resources.jetbrains.com/storage/products/company/brand/logos/jb_beam.png" alt="JetBrains Logo (Main) logo" width="250"></a>
|
||||
|
||||
<br>
|
||||
|
||||
|
||||
Reference in New Issue
Block a user