markdumay/synology-tls

Synology TLS

概述

Synology是知名的网络附加存储（NAS）设备制造商，提供基于Web的用户界面Disk Station Manager（DSM）。Synology TLS 基于acme.sh构建，简化了通过HTTPS安全访问DSM的设置。它使用Let's Encrypt自动颁发和续期特定互联网域名的TLS证书，通过CloudFlare实现DNS验证，使NAS可置于防火墙后而无需将端口暴露到公网。该工具以Docker镜像形式部署，便于简化部署流程，并使用Docker Swarm secrets保护凭据安全。

核心组件

本项目使用以下核心软件组件：

• acme.sh - 纯Unix shell脚本，用于自动从Let's Encrypt颁发和续期免费证书
• Docker - 容器平台（包括Swarm和Compose）

前提条件

Synology TLS可在任何支持Docker的主机上运行，已在macOS Catalina和运行DSM 6.2的Synology NAS上测试通过。其他前提条件如下：

• 需注册域名 - 配置SSL证书以启用对Synology NAS的安全访问需要域名，且需具备配置该域名DNS记录的能力。

• 需Docker Compose和Docker Swarm - Synology TLS需以Docker Swarm模式部署容器，以启用Docker secrets功能。此参考指南介绍如何在主机上初始化Docker Swarm。

• 需CloudFlare账户和令牌 - Synology TLS使用CloudFlare自动配置DNS。CloudFlare提供免费计划，足以满足大多数需求。在CloudFlare首页通过“+ Add a Site”向导添加域名，让CloudFlare管理域名DNS。完成后，需为Synology TLS创建API令牌：从CloudFlare首页进入“My Profile ➡ API Tokens”，创建具有“Zone/Zone/Edit”和“Zone/DNS/Edit”权限的令牌，并在“Zone Resources”中包含你的域名。请妥善保存令牌，因其仅显示一次。

• 需Synology管理员账户 - Synology TLS使用管理员账户自动部署证书，建议创建专用于证书续期的账户。可在DSM中通过“控制面板 ➡ 用户 ➡ 创建”添加用户，确保该账户属于“管理员”组，所有共享文件夹权限设为“无访问”，所有应用权限设为“拒绝”。

测试

建议在部署到NAS前先在本地测试服务。使用docker-compose运行服务可简化验证流程。以下四步可在本地机器上运行服务并验证功能：

步骤1 - 克隆仓库

首先将仓库克隆到本地文件夹。假设已进入目标工作目录，执行以下命令克隆仓库文件（--recurse-submodules确保获取嵌入式子模块），然后进入仓库目录：

console
git clone --recurse-submodules https://github.com/markdumay/synology-tls.git
cd synology-tls

步骤2 - 创建Docker Secrets

由于Docker Compose不支持外部Swarm secrets，测试时需创建本地秘密文件（注意：凭据以明文存储，不建议用于生产环境）。替换以下命令中的CloudFlare（CF_前缀）和Synology（SYNO_）凭据值（见前提条件）：

console
mkdir secrets
printf mail@example.com > secrets/CF_Email.txt
printf password > secrets/CF_Token.txt
printf admin > secrets/SYNO_Username.txt
printf password > secrets/SYNO_Password.txt

步骤3 - 更新环境变量

docker-compose.yml文件使用环境变量简化配置，可使用仓库中的示例文件作为起点：

console
mv sample.env .env

.env文件包含八个变量，需根据需求调整：

步骤4 - 运行Docker服务

使用docker-compose up测试Docker服务：

console
docker-compose up

从Docker Hub拉取镜像后，将显示多个消息。以下为关键环节的日志摘录：

服务启动

启动时，Synology TLS会将acme.sh的cron任务替换为.env中定义的自定义任务，cron日志写入'/var/log/acme.log'：

acme_1 | Removing cron job
acme_1 | LE_WORKING_DIR='/root/.acme.sh'
acme_1 | Using stage ACME_DIRECTORY: https://acme-staging-v02.api.letsencrypt.org/directory
acme_1 | Adding custom cron job at '* 2 * * *'
acme_1 | View the cron log in '/var/log/acme.log'

更新acme.sh

acme.sh脚本定期更新，启动时会下载最新版本，并通过cron定期刷新：

acme_1 | Installing from online archive.
acme_1 | Installed to /root/.acme.sh/acme.sh
acme_1 | Upgrade success!

执行DNS-01验证

Synology TLS使用DNS-01挑战让Let's Encrypt验证域名所有权，无需将NAS暴露到公网。通过CloudFlare自动配置DNS，默认请求主域名和通配符证书：

acme_1 | Create account key ok.
acme_1 | Multi domain='DNS:example.com,DNS:*.example.com'
acme_1 | Let's check each dns records now. Sleep 20 seconds first.
acme_1 | Verifying: example.com
acme_1 | Success
acme_1 | Verifying: *.example.com
acme_1 | Success

下载Let's Encrypt证书

DNS-01挑战通过后，Synology TLS会下载证书，证书和密钥存储在挂载目录data/acme/example.com：

acme_1 | Download cert, Le_LinkCert: https://acme-staging-v02.api.letsencrypt.org/acme/cert/xxx
acme_1 | Cert success.
acme_1 | Your cert is in  /acme.sh/example.com/example.com.cer 

部署证书到NAS

最后一步是自动将证书部署到Synology NAS：

acme_1 | Logging into localhost:5000
acme_1 | Upload certificate to the Synology DSM
acme_1 | Success

默认情况下，Synology TLS作为后台服务运行，通过每日cron任务验证证书。可通过以下命令查看cron日志：

docker exec synology-tls_acme_1 /bin/sh -c 'cat /var/log/acme.log'

部署

生产环境部署步骤与本地测试略有不同，以下四步突出与测试流程的差异：

步骤1 - 克隆仓库

无变化

步骤2 - 创建Docker Secrets

不再使用基于文件的secrets，而是创建安全的Docker secrets。可通过管道创建secrets（注意末尾的-表示使用管道输入），按需更新凭据：

console
printf mail@example.com | docker secret create CF_Email -
printf password | docker secret create CF_Token -
printf admin | docker secret create SYNO_Username -
printf password | docker secret create SYNO_Password -

若不希望在命令行中直接输入敏感信息，可使用仓库/docker-secret目录下的create_secret.sh脚本，该脚本会提示输入秘密并确保敏感数据不在控制台显示：

console
./create_secret.sh CF_Email
./create_secret.sh CF_Token
./create_secret.sh SYNO_Username
./create_secret.sh SYNO_Password

仓库中的docker-compose.yml默认配置用于本地测试，需更新secrets部分以使用Docker secrets：

Dockerfile
secrets:
    CF_Email:
        external: true
    CF_Token:
        external: true
    SYNO_Username:
        external: true
    SYNO_Password:
        external: true

步骤3 - 更新环境变量

无变化，但需在确认一切正常后将TARGET设为production

步骤4 - 运行Docker服务

生产环境中需将Docker服务部署到Docker Stack。与Docker Compose不同，Docker Stack不会自动创建本地文件夹，需先创建acme.sh数据和日志的空文件夹，然后使用docker-compose作为输入部署Docker Stack（确保环境变量正确解析）：

console
mkdir -p data/acme
mkdir -p data/log
docker-compose config | docker stack deploy -c - synology-tls

通过以下命令检查Docker Stack状态：

console
docker stack services synology-tls

若Stack初始化正确，Synology TLS服务的REPLICAS值应为1/1。服务启动可能需要几分钟，可稍后重复执行命令检查：

ID  NAME                MODE        REPLICAS    IMAGE                               PORTS
*** synology-tls_acme   replicated  1/1         markdumay/synology-tls:2.8.6

服务运行后，可通过docker service logs synology-tls_acme查看服务日志，参考步骤4 - 运行Docker服务中的日志验证方法。

调试Swarm服务可能较复杂，若服务未正常启动，可通过docker service ps synology-tls_acme获取任务ID，运行docker inspect <task-id>排查问题。使用docker stack rm synology-tls可完全移除Docker Stack。

使用

已安装的证书可在DSM中通过“控制面板 ➡ 安全性 ➡ 证书”查看，点击“配置”按钮可将证书分配给服务。

贡献

1. 克隆仓库并创建新分支

   $ git checkout https://github.com/markdumay/synology-tls.git -b name_for_new_branch
   

2. 进行并测试更改
3. 提交Pull Request并附详细更改说明

鸣谢

Synology TLS受以下代码仓库和博客文章启发：

• Neilpang - acme.sh的所有者和维护者
• Markus Lippert - 使用DNS-01挑战在Synology NAS上自动续期Let's Encrypt证书
• xFelix - Synology Let's Encrypt DNS-01证书颁发与安装
• Luka Manestar - Let's Encrypt + Docker = 通配符证书

***

许可

Copyright © https://github.com/markdumay