Docker 101: `–restart` Option in Docker

Detailed Explanation of the --restart Option in Docker

The --restart option in Docker allows you to specify a policy that determines whether and under what circumstances a Docker container should be restarted. This option is particularly useful for ensuring the resilience and reliability of services running in containers, as it can help automatically recover from failures or unexpected stops.

1. no: Do Not Automatically Restart the Container

English:

• Description: When you use --restart no (or if you don’t specify the --restart option at all), Docker will not automatically restart the container if it stops or exits for any reason. This is the default behavior.
• Use Case: This option is typically used during development or testing when you want to manually control the lifecycle of the container and inspect it after it stops.

Chinese:

• 描述: 当您使用 --restart no（或者如果您根本不指定 --restart 选项）时，Docker 不会在容器停止或退出时自动重启容器。这是默认行为。
• 使用场景: 该选项通常用于开发或测试期间，当您希望手动控制容器的生命周期并在其停止后进行检查时。

Example Command:

docker run --restart no my-docker-image

2. on-failure: Restart the Container on Failure

English:

• Description: The on-failure option tells Docker to restart the container only if it exits with a non-zero exit code, indicating that the container has failed. You can also specify a maximum number of restart attempts using on-failure:N, where N is the number of attempts.
• Use Case: This option is useful when you want to automatically recover from temporary errors, such as a network issue or a resource limitation, but avoid an infinite restart loop if the problem persists.

Chinese:

• 描述: on-failure 选项告诉 Docker 仅在容器以非零退出代码退出时重启容器，这表明容器已失败。您还可以使用 on-failure:N 指定最大重启尝试次数，其中 N 是尝试次数。
• 使用场景: 当您希望从临时错误（例如网络问题或资源限制）中自动恢复，但避免在问题持续存在时出现无限重启循环时，此选项非常有用。

Example Commands:

docker run --restart on-failure my-docker-image

Example with a limit:

docker run --restart on-failure:5 my-docker-image

• Explanation: In the second example, Docker will attempt to restart the container up to 5 times if it fails. If the container continues to fail after 5 attempts, it will not be restarted again.

中文翻译:

docker run --restart on-failure:5 my-docker-image

• 解释: 在第二个示例中，如果容器失败，Docker 将尝试重启该容器最多 5 次。如果容器在 5 次尝试后继续失败，则不会再次重启它。

3. always: Always Restart the Container

English:

• Description: The always option ensures that the container is restarted whenever it stops, regardless of the exit code. This means the container will restart even if it was stopped manually, unless the Docker daemon itself is stopped or the container is removed.
• Use Case: This option is ideal for production environments where you want to ensure that a service is always running. It’s particularly useful for critical services that need to be highly available.

Chinese:

• 描述: always 选项确保容器在停止时始终重启，无论退出代码如何。这意味着即使容器被手动停止，也会重启它，除非 Docker 守护进程本身停止或容器被删除。
• 使用场景: 该选项非常适合生产环境，在这种环境中，您希望确保服务始终运行。对于需要高度可用的关键服务，它特别有用。

Example Command:

docker run --restart always my-docker-image

• Explanation: This command will start a container that will always restart if it stops, ensuring continuous availability.

中文翻译:

docker run --restart always my-docker-image

• 解释: 该命令将启动一个容器，如果它停止，将始终重启，确保持续可用性。

4. unless-stopped: Restart Unless Explicitly Stopped by the User

English:

• Description: The unless-stopped option is similar to always, but with one key difference: Docker will not restart the container if it was stopped by the user with docker stop. This option ensures that the container restarts automatically if it stops unexpectedly, but stays stopped if you deliberately stop it.
• Use Case: This option is useful when you want the container to automatically recover from crashes or reboots but allow it to remain stopped after a manual intervention.

Chinese:

• 描述: unless-stopped 选项类似于 always，但有一个关键区别：如果用户使用 docker stop 停止了容器，Docker 将不会重启容器。此选项确保容器在意外停止时自动重启，但在您有意停止后保持停止状态。
• 使用场景: 当您希望容器在崩溃或重启后自动恢复，但允许其在手动干预后保持停止时，此选项非常有用。

Example Command:

docker run --restart unless-stopped my-docker-image

• Explanation: This command starts a container that will automatically restart unless it was explicitly stopped by the user.

中文翻译:

docker run --restart unless-stopped my-docker-image

• 解释: 该命令启动一个容器，除非用户明确停止它，否则它将自动重启。

Summary of Restart Policies

1. Tips

• English: Use on-failure with a limit (e.g., on-failure:5) to avoid containers stuck in an infinite restart loop due to persistent errors.
• Chinese: 使用带限制的 on-failure（例如 on-failure:5）以避免容器因持续错误而陷入无限重启循环。

2. Warning

• English: Be cautious with the always and unless-stopped policies in development environments, as they can cause containers to restart unexpectedly during testing.
• Chinese: 在开发环境中使用 always 和 unless-stopped 策略时要小心，因为它们可能会导致容器在测试期间意外重启。

This detailed explanation should help you choose the appropriate restart policy for your Docker containers, depending on your specific use case and environment.