最近捣鼓Docker部署的Alist时最折腾人的一件事就是HTTPS证书。浏览器地址栏那个“不安全”的红色警告对于自建网盘、影视库或者给朋友分享文件的人来说实在是碍眼。更麻烦的是直接用Docker跑的Alist你在后台界面里填一个证书路径重启容器后经常发现根本没生效——这不是Alist的锅是Docker的隔离机制在作怪。这篇文章就专门聊清楚Docker环境下的Alist怎么正确添加SSL证书从证书选型、申请下载到两种落地部署方案再到我踩过的坑一次讲透。这套内容适合用Docker跑Alist的人不管你是装在NAS、云服务器还是虚拟机里只要想让Alist走HTTPS都可以照着做。我自己用的是内网Nginx反代的方案这篇也重点讲它如果你只是纯局域网访问后面也给了直挂证书的备选玩法。1. 先搞清楚一件事Docker环境下的证书该交给谁1.1 为什么Alist后台配置了证书却总不生效很多第一次搞的人包括我当年第一反应都是去Alist后台“设置 - 全局”里找证书配置项填上证书文件路径再把Scheme改成https。但你会发现Docker部署下这套操作经常失败或者重启容器后配置直接丢了。原因在于Docker容器的文件系统是隔离的。你写在Alist界面里的路径是容器内部的路径不是你宿主机上的路径。如果容器里根本不存在那个文件Alist自然加载不出来。更关键的是容器本身的写层是不持久的——当你用docker run创建容器后容器内的修改都存在于临时可写层一旦容器被删除重建这些配置和文件全部消失。所以如果你把证书文件复制进容器内部而不是挂载进容器下次更新镜像或重建容器时证书就没了。另一个隐蔽问题Alist本身虽然支持直接读取证书启动HTTPS但它在Docker环境里单独挂443端口会和你宿主机上其他HTTPS服务冲突。如果你服务器上已经跑了Nginx、Caddy或者其他网站再让Alist容器去抢443端口必然出问题。所以Docker里部署的Alist最稳妥的思路是证书不要交给Alist进程自己管理而是交给前置的反向代理统一处理。这样证书生命周期、续期、多个服务的端口复用全都变成代理层的事Alist只需要老老实实跑HTTP。1.2 证书放哪一层决定了你后面省不省心把HTTPS终止在反向代理层是Docker部署Web服务最常见的模式。你可以把Nginx、Caddy或者Traefik想象成小区的门卫证书是门禁卡门卫验证完访客身份再放行到里面各个房间。Alist就是其中一个房间它自己不需要知道访客长什么样只需要服务门卫转发过来的内部请求。这个模式有几个实际好处443端口只被代理程序占用Alist、Nextcloud、Jellyfin等所有内网服务都能共用这一个端口通过不同域名或子路径区分。证书续期、替换只影响代理容器业务容器完全不用动。Alist容器可以保持最简配置升级镜像时不需要重新配置证书相关的东西。如果你不搞反代非要把证书塞给Alist容器也不是不行——纯局域网环境、没有其他Web服务、不在乎重建容器后要重新配置那你可以直接用Alist的cert配置。但这个方案只建议内网自用一旦你打算暴露到公网或者服务比较多直接上Nginx更省事。1.3 三种证书渠道怎么选更合适证书类型有效期申请难度适用场景阿里云/腾讯云免费证书通常1年可自动续期低控制台点几下有云厂商账号、有备案域名、想要省心的用户Lets Encrypt90天中需配置自动化续期想完全免费、愿意折腾自动化的用户自签证书自定低但浏览器警告纯内网访问、设备少、能接受安装信任证书如果你有域名我优先推荐云厂商免费证书。申请流程就是控制台点点点下载下来一个压缩包里面是xxx.pem证书链和xxx.key私钥这俩文件正是Nginx要的。阿里云现在有免费证书自动续期功能开启后每年换一次基本不用你操心。Lets Encrypt强在自动化用acme.sh或Caddy可以做到证书到期前自动续签适合没有云厂商账号或者域名在海外注册的场景。但它有90天有效期如果没配自动化你三个月就要手动搞一次容易忘所以拿它前要有心理准备。自签证书我就不多推荐了。它的核心问题是浏览器的“不安全”警告无法消除你要是自己用还能忍给朋友分享链接时别人多半以为你网站有问题。除非你是彻底断网的内网环境否则还是老老实实用有公信力的证书。2. 证书获取申请、下载与续期的细节2.1 阿里云免费证书申请到下载的完整流程先说明一下这里提到的流程不只适用于阿里云腾讯云、华为云等主流云厂商的免费证书申请逻辑类似基本都能对上。第一步登录阿里云控制台搜索“数字证书管理服务”也叫SSL证书。进入后左侧菜单找到“证书申请”选择“免费证书”。注意免费证书一般只能申请单域名证书也就是一个证书只能绑一个域名。如果你的Alist走的是alist.example.com那就申请这个域名的证书。第二步填写申请信息。你需要填一个域名然后选择验证方式一般用DNS验证。如果你的域名DNS解析也在阿里云它甚至可以帮你自动添加一条解析记录完成验证如果域名在别的注册商需要手动去DNS后台加一条TXT记录等它生效。这里有个容易踩的坑DNS验证记录有有效期有些人是申请完忘了点击“验证”等半天才发现。操作顺序应该是提交申请 → 添加DNS记录 → 点击“验证”按钮 → 等待签发。整个过程快的几分钟慢的半小时也够了。第三步证书签发后在证书列表找到这条记录点击“下载”。这时候弹出来一个选择框里面罗列了Nginx、Apache、IIS、Tomcat等常见服务器类型。一定要选Nginx因为Nginx类型下载下来是两个文件一个xxx.pem、一个xxx.key正好是标准配置需要的格式。关于续期现在免费证书在控制台可以开启“自动续期”到期前阿里云会自动申请新证书并替换。但要注意自动续期只是云厂商侧帮你签发了新证书你的服务器上那份文件不会自动更新你需要重新下载、替换、reload Nginx。这个细节后面排查部分还会提到。2.2 用acme.sh自动化申请Lets Encrypt证书如果你不想依赖云厂商Lets Encrypt是个好选择。配合acme.sh这个脚本能做到完全自动签发和续期。先说安装。在宿主机上执行curl https://get.acme.sh | sh -s email你的邮箱这个邮箱是用于Lets Encrypt到期提醒的。安装完成后脚本会默认放在~/.acme.sh/目录下并自动配置好shell alias。然后签发证书。如果你暂时不想用DNS API最简单的方式是用HTTP验证但前提是你的域名80端口的HTTP请求能正常访问到这台服务器。如果环境不满足建议用DNS API。比如你域名的DNS托管在阿里云需要先去阿里云RAM控制台创建一个子账号授权DNS管理的权限拿到AccessKey ID和Secret然后告诉acme.shexport Ali_Key你的AccessKey ID export Ali_Secret你的AccessKey Secret acme.sh --issue --dns dns_ali -d alist.example.comacme.sh会自动调用阿里云API添加TXT记录等验证通过后完成签发。签出来的证书文件会在~/.acme.sh/alist.example.com/目录下其中fullchain.cer和alist.example.com.key是后面要用的文件。自动续期这一块acme.sh 安装时会自动添加一条cron任务每天检查一次到期前30天内自动续签。你只要在cron里加上一条reload Nginx的命令就行。我的做法是改一下~/.acme.sh/acme.sh --cron --home /root/.acme.sh这个crontab在续签成功后触发Nginx容器重新加载证书。一个典型的cron写法30 3 * * * /root/.acme.sh/acme.sh --cron --home /root/.acme.sh /dev/null加上这一条之后证书到期前会自动换掉Nginx那边我配合--reloadcmd参数自动刷新acme.sh --install-cert -d alist.example.com \ --key-file /data/certs/alist.key \ --fullchain-file /data/certs/alist.pem \ --reloadcmd docker exec nginx nginx -s reload这样证书直接放到宿主机固定目录续签完自动reload全程不需要人工干预。2.3 证书文件格式与内容辨认拿到证书后你可能想知道这两个文件里装的是什么。pem文件或者叫fullchain是由几段Base64文本组成的开头是-----BEGIN CERTIFICATE-----里面一般包含了你的域名证书和中间证书链。key文件开头是-----BEGIN PRIVATE KEY-----或者-----BEGIN RSA PRIVATE KEY-----。区别这俩文件很简单包含“PRIVATE KEY”字样的是私钥绝对不能泄露只包含“CERTIFICATE”字样的就是公钥证书部分。私钥一旦泄露等于把HTTPS的加密大门钥匙给了别人所以证书文件权限最好设置成644目录设置成755避免其他用户能读。另外现在新申请的证书签名的哈希算法都是SHA-256如果你的证书老到还在用SHA-1签名浏览器会提示弱签名问题CVE-2005-4900相关的报错在Windows等老客户端上尤其常见。遇到这种报错不用去服务器上折腾补丁直接换一张新证书就行。3. 两种落地部署方案反代优先直挂备用3.1 方案A内网Nginx反向代理我最推荐这种方案的核心是Nginx容器监听宿主机443端口持有证书文件把HTTPS请求转发给同一个Docker网络里的Alist容器。Alist容器只监听自己的HTTP端口默认5244具体看你的版本和创建时的端口映射。先梳理一下整体拓扑。假设你的域名是alist.example.com证书放在宿主机/data/certs/目录下Nginx用nginx:alpine镜像跑在443端口Alist容器和Nginx容器在同一个自定义bridge网络里Alist的容器名是alist。那么Nginx的配置文件长这样server { listen 443 ssl; server_name alist.example.com; ssl_certificate /etc/nginx/certs/alist.pem; ssl_certificate_key /etc/nginx/certs/alist.key; ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers HIGH:!aNULL:!MD5; client_max_body_size 0; location / { proxy_pass http://alist:5244; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } }这里有几个点要重点解释一下。ssl_certificate和ssl_certificate_key是Nginx读取证书的关键配置注意路径是容器内部路径——宿主机/data/certs/挂载到容器里的/etc/nginx/certs/所以配置文件里写的是后者。client_max_body_size 0一定要加上。Alist作为网盘程序文件上传是刚需。如果不设置这个参数Nginx默认限制上传大小为1M你往网盘传个大文件就直接413错误。设成0表示不限制上传大小交给后端Alist处理。proxy_set_header这几个字段决定转发请求时携带什么信息。Host $host让Alist知道你访问的是哪个域名X-Real-IP和X-Forwarded-For让Alist拿到真实的客户端IPX-Forwarded-Proto $scheme让Alist知道你走的是HTTPS否则Alist后台生成的下载链接可能会是http开头的导致在HTTPS页面里出现混合内容被浏览器拦截。如果你要更稳妥可以再加WebSocket支持因为Alist后台有些长连接功能需要它proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_http_version 1.1;然后Nginx容器的启动命令大概是这样docker run -d --name nginx-proxy \ -p 443:443 \ -v /data/certs:/etc/nginx/certs:ro \ -v /data/nginx/conf.d:/etc/nginx/conf.d:ro \ --network 你的自定义网络 \ --restart unless-stopped \ nginx:alpine注意挂载方式用了:ro意思是容器内只读。这能防止Nginx侧误改动证书文件也减少权限问题的出错面。Alist容器不用改端口映射里与443相关的东西保持它原来的HTTP端口即可。如果你创建的Alist容器之前映射过443或者80建议清理掉让入口只由Nginx接管。3.2 方案B不搞反代证书直接挂给Alist有些场景不需要反代比如你只是个纯局域网访问、没有第二台机器、也不打算将来扩展更多服务。那你可以把证书直接交给Alist容器省一层。Alist本身支持指定HTTPS证书文件启动。在官方Docker镜像的环境变量里可以通过ALIST_HTTPS_CERT和ALIST_HTTPS_KEY传入这两个配置。你只需要在创建容器时把宿主机证书目录挂载进去再设置环境变量指向容器内的路径即可。一个完整的docker run示例docker run -d --name alist \ -p 5244:5244 \ -v /data/alist:/opt/alist/data \ -v /data/certs:/data/certs:ro \ -e ALIST_HTTPS_CERT/data/certs/alist.pem \ -e ALIST_HTTPS_KEY/data/certs/alist.key \ --restart unless-stopped \ xhofe/alist:latest这里证书目录挂载进容器后Alist启动时会自动加载证书走HTTPS。端口还是映射到5244但访问时浏览器会直接用HTTPS协议Alist内部自动完成握手加密。这个方案的好处是少一个组件磁盘、内存占用更小排查链路也短。坏处有三点第一如果你在Docker宿主上还有其他服务要占用443端口这个方案就玩不转了因为Alist没法绑定在443以外的HTTPS端口上让你浏览器直接访问除非你愿意在URL后面带端口号。第二证书续期后需要重启Alist容器才能加载新证书。省了反代也不算全省多少有点麻烦。第三如果将来要加其他服务比如再挂一个Jellyfin、Nextcloud你又得重新规划一层反代等于走回头路。所以我个人建议哪怕你暂时只有一个Alist只要你的环境允许尽量上Nginx反代一步到位。3.3 端口、网络和挂载三个容易出错的配置点方案A和方案B都绕不开这三个配置点我单独拿出来说说。端口方面务必确认Alist实际监听端口和你compose里写的端口一致。不同版本的Alist默认端口不太一样有的用5244、有的用5248所以最稳妥的做法是看容器日志或者docker ps里显示的端口映射。凡是在配置里写端口的地方都要前后对应特别是Nginx里proxy_pass http://alist:5244;这个5244要改成你Alist容器的实际端口。网络方面Nginx容器里用容器名解析Alist的前提是两者在同一个Docker自定义网络里。如果你用默认的bridge网络容器名可以互相ping通吗不一定。最好创建一个自定义网络docker network create alist-net创建容器时加上--network alist-net这样Nginx和Alist才能通过容器名互相访问。如果用docker compose直接在compose文件里声明一个network两个service都加进去就行。挂载方面最容易翻车的是权限。证书文件在宿主机上属主可能是一个普通用户Nginx容器里的进程以nginx用户运行如果目录权限太紧比如700Nginx容器就完全读不了。我的习惯是证书目录放/data/certs目录权限755证书文件权限644私钥文件权限600。这样既保证Nginx能读又不至于让私钥变成全世界可读。4. 配置失败的常见原因与排查实录4.1 证书配了但浏览器还是提示不安全这个现象是出现率最高的。正常情况下配完证书后浏览器地址栏是小锁如果还是显示不安全从头到尾查这几个地方。先确认你访问的协议。有些人证书配完了但浏览器里保存的还是http://alist.example.com这个地址或者Nginx只监听了443端口没做80跳转访客手动输域名默认走80端口自然走不到HTTPS。这个好治加个80跳转server { listen 80; server_name alist.example.com; return 301 https://$host$request_uri; }再确认证书绑定的域名和访问域名是否一致。证书里有CN字段和SAN扩展里面列的域名和你浏览器访问的域名必须完全匹配。证书申请的是alist.example.com你用192.168.1.10直接访问IP那肯定报错。顶级域名的证书也不能覆盖子域名反过来也一样。最后用命令直接验证证书链。在宿主机上执行openssl s_client -connect 127.0.0.1:443 -servername alist.example.com -showcerts如果输出的结果里能看到完整的证书链并且最后一行是Verify return code: 0 (ok)说明证书链路没问题。如果看到Verify return code: 21 (unable to verify the first certificate)多半是你用的ssl_certificate只是域名证书本身没有包含中间证书链把配置换成fullchain文件或者在Nginx里把ssl_trusted_certificate指到中间证书路径即可。4.2 Nginx容器里读不到证书文件报错通常长这样nginx: [emerg] cannot load certificate key后面跟一串路径。这种情况九成是挂载路径或权限问题。先自查挂载路径是否写反了。-v /data/certs:/etc/nginx/certs:ro这个命令的格式是“宿主机路径:容器内路径”宿主机的/data/certs下必须有证书文件容器内的/etc/nginx/certs里才能看到。如果你把配置里的路径写成了宿主机的绝对路径Nginx容器当然找不到因为容器里没有这个路径。权限问题的排查方法是先进容器看能不能读取文件docker exec -it nginx-proxy ls -l /etc/nginx/certs/ docker exec -it nginx-proxy cat /etc/nginx/certs/alist.key如果cat报权限拒绝就是文件权限太紧。在宿主机上把私钥文件改成600、证书文件改成644目录至少755再重启Nginx容器基本就好了。还有一个冷门坑如果你用SELinux强制模式的操作系统比如CentOS挂载的只读目录也可能被SELinux拦截。磁盘挂载后在容器里看不到文件或者看到但读不了多半是SELinux的container_file_t标签问题。临时方案是关闭SELinux测试不推荐长期正规做法是给目录打标签chcon -Rt container_file_t /data/certs4.3 容器重建后证书配置全没了这个问题我在1.1里提到过但实际触发场景值得再强调一下。很多人用docker run创建Alist容器时证书文件是直接复制进容器里的比如执行了docker cp cert.pem 容器ID:/opt/alist/。当时用着没问题但某天Alist升级你重新创建容器后发现后台配置还在、证书文件路径还在但文件本身没了——因为新容器是从镜像创建的全新可写层你docker cp进去的东西早就随着旧容器销毁而丢失了。所以记住这条铁律凡是容器里需要持久保存的文件一律用宿主机目录挂载不要复制进容器里。证书、数据库文件、配置文件统统用-v挂载。这也是为什么我前面所有示例都强调-v /data/certs:/data/certs:ro这种写法。只要挂载了无论容器怎么重建文件都在宿主机上稳稳躺着。4.4 阿里云续期后证书没自动更新通过阿里云控制台开启自动续期后云厂商会在旧证书到期前自动签发新证书但新证书只是一个线上资源不会自动跑到你服务器上。你需要在控制台下载新的Nginx证书文件替换宿主机/data/certs里对应的文件然后重载Nginxdocker exec nginx-proxy nginx -s reload如果懒得每年手动换一次其实更适合用2.2节说的acme.sh方案证书自动续签、自动部署、自动reload全程无人值守。云厂商免费证书适合不想折腾的人但“自动续期”并不等于“自动部署”这句话你操作一次后会深有体会。4.5 配置错误排查顺序速查表现象排查点高概率原因修复动作浏览器显示连接不安全协议/域名/证书链访问的还是HTTP或域名不匹配加80跳转检查证书域名换fullchainNginx启动报certificate key错误挂载路径/文件权限路径写错或私钥权限太紧检查-v方向chmod 600 key、644 pemAlist重启后证书丢失持久化方式证书被复制进容器可写层改为宿主机目录挂载续期后HTTPS仍显示旧证书部署链路服务器文件未替换/未reload重新下载、替换、nginx -s reload上传大文件报413Nginx配置client_max_body_size未设置加client_max_body_size 0结尾给我自己的Alist配SSL证书那次前后折腾了两天走了不少弯路。现在我的固定操作流程是证书统一放宿主机/data/certs目录所有容器挂载这个目录Nginx反代统一管理443端口Alist只跑HTTP。续期用acme.sh自动完成cron里写好reload命令证书到期基本无感。这套思路不光适用于Alist你后面加跑其他Web服务比如Home Assistant、Jellyfin、Nextcloud都是同一个套路容器跑HTTP证书交给反向代理层。希望这篇内容能让你少走点弯路配置一次就稳稳跑起来。