舞浅静的博客

SSH 远程端口转发无法启动：直接登录正常但隧道卡住

Fri, 12 Jun 2026 00:00:00 GMT

环境

客户端：OpenSSH 任意版本
服务端：Ubuntu 24.04、OpenSSH不知道什么版本
认证方式：公钥认证
转发类型：远程端口转发（-R）

问题

今天心血来潮想喝杯奶茶，出门时直接笔记本一盖就出门了，到了奶茶店想要通过 SSH Tunnel 让服务器使用本机代理时，发现一直无法建立隧道。排查日志发现通过 SSH 建立远程端口转发隧道时，客户端日志显示认证成功、连接建立，但在 Starting a new Remote Port-Forwarding rule 后不再有任何进展，隧道无法使用。但直接执行 SSH 登录（不带 -R 参数）可以正常连接和操作。

排查过程

1. 观察客户端日志

日志关键部分如下（已脱敏）：

👤 Starting a new connection to: "login.example.com" port "22"
⚙️ Agreed KEX algorithm: curve25519-sha256
⚙️ Handshake finished
👤 Authenticated to "login.example.com":"22"
👤 Starting a new Remote Port-Forwarding rule   # 此后卡住

没有报错，也没有成功绑定端口的提示。直接 ssh user@host -p 22 则可正常登录。

2. 检查服务器端口占用

登录到远程服务器（通过普通 SSH 会话），查看拟转发的端口是否已被监听：

sudo netstat -tulnp | grep :7897

发现该端口处于 LISTEN 状态，且对应的进程是 sshd 的子进程。这意味着之前的某个 SSH 隧道没有正常关闭，残留的 sshd 进程仍然占用了转发端口。

3. 清理残留进程

找到残留进程的 PID 后，可以直接杀死该进程，或者终止当前用户的所有 sshd 子进程：

pkill -u <myuser> sshd

注意：该命令会同时杀死您当前正在使用的 SSH 会话，需要重新登录。

4. 重新尝试隧道

清理完成后，再次发起远程端口转发：

ssh -R 7897:localhost:7897 <myuser@login.example.com> -p <port>

隧道成功建立，问题解决。

根因分析

正常流程

当客户端通过 -R 请求远程转发时，SSH 服务器会启动一个监听进程绑定到指定的远程端口。
客户端断开连接时，正常情况下服务器端的监听进程也会随之关闭，端口被释放。

异常残留

以下情况可能导致服务器的子进程未能正常退出：

客户端被强制终止（kill -9、网络中断、电源断电）
SSH 复用（ControlMaster）异常
服务器端 sshd 配置问题或资源限制

残留的 sshd 进程仍保持着对目标端口的绑定。当新客户端请求相同端口的转发时，由于端口已被占用（Address already in use），服务器不会返回成功信息，客户端可能表现为卡住或超时。

为什么普通登录正常？

普通登录（不包含 -R 选项）不涉及端口绑定，因此不受残留进程的影响。

附录：脱敏后的完整日志供参考

以下为脱敏后的客户端日志（包含成功认证和启动转发卡住的片段）：

👤 Starting a new connection to: "login.example.com" port "22"
⚙️ Starting address resolution of "login.example.com"
⚙️ Address resolution finished
⚙️ Connecting to "203.0.113.10" port "22"
👤 Connection to "login.example.com" established
⚙️ Starting SSH session
⚙️ Remote server: SSH-2.0-OpenSSH_9.6p1 Ubuntu-3ubuntu13.16
⚙️ Agreed KEX algorithm: curve25519-sha256
⚙️ Agreed Host Key algorithm: ecdsa-sha2-nistp256
⚙️ Agreed server-to-client cipher: aes256-gcm@openssh.com MAC: INTEGRATED-AES-GCM
⚙️ Agreed client-to-server cipher: aes256-gcm@openssh.com MAC: INTEGRATED-AES-GCM
⚙️ Agreed client-to-server compression: none
⚙️ Agreed server-to-client compression: none
⚙️ Handshake finished
👤 Checking host key: SHA256:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
👤 Host "login.example.com":"22" is known and matches
👤 Authenticating to "login.example.com":"22" as "myuser"
⚙️ Available client authentication methods: publickey,password,keyboard-interactive
⚙️ Authentication that can continue: publickey
👤 Authenticating using publickey method
👤 Authentication succeeded (publickey)
👤 Authenticated to "login.example.com":"22"
👤 Starting a new Remote Port-Forwarding rule   # 此处卡住

总结

SSH 远程端口转发失败但普通登录正常时，首先怀疑服务器端是否有残留的 sshd 进程占用了目标端口。通过 pkill -u 用户名 sshd 清理后问题大多可解决。建议在客户端添加 ExitOnForwardFailure=yes 以便快速发现冲突，并在服务器端合理配置连接保活参数，减少残留发生的概率。

Slurm NFS 挂载后 IO error 排障记录

Fri, 22 May 2026 00:00:00 GMT

为了信息脱敏，正文内所有的用户名和具体ip等敏感内容用<>代替

背景

集群里有一台登录节点 2.login.slurm.lan，三台计算节点，均在<allowed ip range>下：

1.compute.slurm.lan
2.compute.slurm.lan
3.compute.slurm.lan

故障发生前，集群交换机经历了一次异常断电并恢复。恢复后，计算节点上的 NFS 挂载表面存在，但访问 /home 和 /opt 时会出现超时或 Input/output error，进而导致 Slurm 任务无法正常启动。

存储服务器通过 NFS 导出两个目录：

<nfs server ip>:/mnt/Data/slurm/userhome 挂载到 /home
<nfs server ip>:/mnt/Data/slurm/opt 挂载到 /opt

其中 /home 提供用户目录，例如 /home/sshusers/<user>；/opt 里有 Slurm 的 TaskProlog 依赖脚本：

/opt/shell_related/task_prolog.sh

因此这两个 NFS 挂载都必须正常。只挂上 /home 不够，/opt 访问失败会直接导致 Slurm 任务启动失败。

故障现象

最初在 2.compute.slurm.lan 上运行：

srun -c 8 -w 2.compute.slurm.lan hostname

报错：

srun: error: 2.compute.slurm.lan: task 0: Exited with exit code 1
[2026-05-22T15:40:21.638] error: run_command: slurm task_prolog can not be executed (/opt/shell_related/task_prolog.sh) No such file or directory
[2026-05-22T15:40:21.638] error: slurm task_prolog did not exit normally. reason: Run command failed - configuration error
[2026-05-22T15:40:21.638] error: TaskProlog failed status=1

节点上直接访问 NFS 路径时，可见类似现象：

ls /home/sshusers/<user>

ls: reading directory '/home/sshusers/<user>': Input/output error

访问 /opt 也会失败：

head -1 /opt/shell_related/task_prolog.sh

head: cannot open '/opt/shell_related/task_prolog.sh' for reading: Input/output error

内核日志里能看到 NFS 超时：

nfs: server <nfs server ip> not responding, timed out

复现方式

在计算节点上复现主要看三个层面。

检查 /home：

timeout 10 ls -la /home/sshusers/<user>

检查 /opt：

timeout 10 head -1 /opt/shell_related/task_prolog.sh

检查 Slurm：

srun -c 8 -w 2.compute.slurm.lan hostname

对 GPU 节点 1.compute.slurm.lan，需要指定 GPU 分区和资源：

srun -p gpu --gres=gpu:1 -c 8 -w 1.compute.slurm.lan hostname

如果 NFS 正常，这些命令应该分别能读目录、读 prolog 脚本，并输出节点 hostname。

初始检查

查看 NFS 导出：

showmount -e <nfs server ip>

导出内容包含：

/mnt/Data/slurm/opt      <allowed ip range>
/mnt/Data/slurm/userhome <allowed ip range>

说明计算节点所在网段 <allowed ip range> 有权限访问导出。

检查 RPC 服务：

rpcinfo -p <nfs server ip>

能看到 NFS v3 和 v4：

100003    3   tcp   2049  nfs
100003    4   tcp   2049  nfs

这说明服务端 NFS 服务本身是可见的。

尝试不同NFS参数和版本

一开始计算节点上的 /etc/fstab 使用过 NFSv3、systemd automount、soft 等不同组合。为了先恢复访问，尝试过 NFSv3：

<nfs server ip>:/mnt/Data/slurm/userhome /home nfs _netdev,defaults,noatime,nolock,nordirplus,soft,timeo=30,retrans=2,actimeo=1800,vers=3,proto=tcp,mountproto=tcp 0 0
<nfs server ip>:/mnt/Data/slurm/opt /opt nfs _netdev,defaults,noatime,nolock,nordirplus,soft,timeo=30,retrans=2,actimeo=1800,vers=3,proto=tcp,mountproto=tcp 0 0

其中 nordirplus 很关键：在早期故障状态下，NFSv3 默认的 readdirplus 读目录会触发 Input/output error，加上 nordirplus 后能暂时让目录读取恢复。

但这只是绕过了一部分症状。后续发现真正的底层问题不在 NFS 版本，而在网络 MTU。

定位到 MTU

登录节点访问 NFS 正常，而计算节点访问 NFS 出现 Input/output error。对比网络配置时发现：

登录节点到存储网络的 MTU 是 1500：

enp4s0np0 mtu 1500

计算节点 2、3 的存储网络是 bond，MTU 是 9000：

bond0 mtu 9000

计算节点 1 的存储网卡是：

enp196s0d1 mtu 9000

当交换机端口还没有完全打开巨型帧时，小包 ping 能通：

ping -c 1 <nfs server ip>

但巨型帧 ping 不通：

ping -M do -s 8972 -c 1 <nfs server ip>

NFS 的表现是：挂载握手、stat 这类小元数据请求可能成功，但读目录、读文件这种较大的请求会超时或 Input/output error。

这解释了为什么故障看起来像 NFS 版本或 fstab 选项问题，其实底层是链路 MTU 不一致。

临时验证

先在 2.compute.slurm.lan 上临时把 MTU 改成 1500：

ip link set dev bond0 mtu 1500
ip link set dev ens2 mtu 1500
ip link set dev ens2d1 mtu 1500

然后重新挂载：

umount -fl /home /opt
mount -v /home
mount -v /opt

验证通过：

timeout 10 ls -la /home/sshusers/<user>
timeout 10 head -1 /opt/shell_related/task_prolog.sh
srun -c 8 -w 2.compute.slurm.lan hostname

这证明故障与巨型帧链路有关。

交换机修复

随后在交换机侧把相关端口 MTU 打开到 9216。再次在计算节点上测试 9000 MTU。

在交换机端口 MTU 设置完成并等待端口重新上线后，NFS 访问恢复正常。结合故障前的异常断电，推测原因是交换机之前只修改了运行时配置，但没有把配置写入 ROM；交换机重启后端口实际支持的帧大小回退，低于计算节点的 MTU 9000，导致 NFS 大包读目录、读文件时失败。

2.compute.slurm.lan：

ping -M do -s 8972 -c 1 <nfs server ip>

成功：

8980 bytes from <nfs server ip>: icmp_seq=1 ttl=64 time=0.148 ms

NFS 访问也成功：

timeout 10 ls -la /home/sshusers/<user>
timeout 10 head -1 /opt/shell_related/task_prolog.sh

Slurm 验证成功：

srun -c 8 -w 2.compute.slurm.lan hostname

输出：

TaskProlog executed at Fri May 22 16:09:44 UTC 2026
2.compute.slurm.lan

后续补开 1.compute.slurm.lan 对应交换机端口后，1 的巨型帧 ping 也恢复：

8980 bytes from <nfs server ip>: icmp_seq=1 ttl=64 time=0.090 ms

最终切回 NFSv4.2

在 MTU 修复后，重新测试 NFSv4.2，发现三台计算节点均可正常使用。最终不再需要 NFSv3 的 nolock、nordirplus、mountproto=tcp 等选项。

最终三台计算节点的 /etc/fstab NFS 行统一为：

<nfs server ip>:/mnt/Data/slurm/userhome /home nfs _netdev,defaults,noatime,soft,timeo=30,retrans=2,actimeo=1800,proto=tcp,vers=4.2 0 0
<nfs server ip>:/mnt/Data/slurm/opt /opt nfs _netdev,defaults,noatime,soft,timeo=30,retrans=2,actimeo=1800,proto=tcp,vers=4.2 0 0

实际挂载确认：

nfsstat -m

可以看到：

/home from <nfs server ip>:/mnt/Data/slurm/userhome
 Flags: rw,noatime,vers=4.2,...

/opt from <nfs server ip>:/mnt/Data/slurm/opt
 Flags: rw,noatime,vers=4.2,...

最终验证

1.compute.slurm.lan：

srun -p gpu --gres=gpu:1 -c 8 -w 1.compute.slurm.lan hostname

输出：

TaskProlog executed at Sat May 23 00:18:41 CST 2026
1.compute.slurm.lan

2.compute.slurm.lan：

srun -c 8 -w 2.compute.slurm.lan hostname

输出：

TaskProlog executed at Fri May 22 16:18:01 UTC 2026
2.compute.slurm.lan

3.compute.slurm.lan：

srun -c 8 -w 3.compute.slurm.lan hostname

输出：

TaskProlog executed at Fri May 22 16:20:12 UTC 2026
3.compute.slurm.lan

三台节点均确认：

ls /home/sshusers/<user>
head -1 /opt/shell_related/task_prolog.sh

均正常。

总结

这次故障表面上是 NFS 挂载失败和 Slurm TaskProlog 执行失败，实际根因是计算节点到存储服务器之间的巨型帧 MTU 配置不一致。更具体地说，交换机异常断电恢复后，运行时 MTU 配置没有从 ROM 中恢复到预期状态，导致交换机端口支持的帧大小小于计算节点 MTU。

排查时几个关键点：

不要只看 mount 是否成功。NFS 可能已经挂上，但读目录或读文件时才报 Input/output error。
showmount、rpcinfo 成功只能说明服务可见，不代表数据路径没有 MTU 问题。
对巨型帧场景，必须用 ping -M do -s 8972 <server> 验证端到端 MTU。
记得在设置完交换机的巨型帧后，要把运行时配置写入 ROM，避免异常断电或重启后配置丢失。

最终修复手段为：

存储网络链路端到端支持 MTU 9000，交换机端口 MTU 开到 9216。

MACE多卡训练无法保存模型

Thu, 19 Mar 2026 00:00:00 GMT

环境

Python 3.11
PyTorch（通过 torchrun 进行 DDP 分布式多进程训练）
e3nn（含 @compile_mode("script") 装饰器）
CP-MACE（deps/CP-MACE/）

问题描述

使用 CP-MACE 进行多卡（DDP）训练时，训练过程本身正常完成，但在训练结束后的模型保存阶段崩溃，抛出：

_pickle.PickleError: ScriptFunction cannot be pickled

排查过程

1. 现象：训练完成后崩溃

WandB 上观察到模型总是在训练成功结束后立即崩溃。将 max_num_epochs 设为 1 以快速复现，日志显示训练本身能正常启动和收敛：

2026-03-18 22:28:11.051 INFO: Using gradient clipping with tolerance=10.000
2026-03-18 22:28:11.052 INFO: ===========TRAINING===========
2026-03-18 22:28:11.052 INFO: Started training, reporting errors on validation set
2026-03-18 22:28:11.052 INFO: Loss metrics on validation set
2026-03-18 22:28:42.950 INFO: Initial: head: default, loss=0.83482060, RMSE_E_per_atom= 949.164 meV, RMSE_F= 267.246 meV / A, RMSE_P=  0.0069 V,

# 后续将没有内容了，wandb上status显示crashed

初步判断问题出在训练完成后的收尾阶段。

2. 定位到 DDP 分布式进程异常

查看 torchrun 日志，发现子进程抛出了 ChildFailedError：

Traceback (most recent call last):
  File "/.conda/envs/catdt/bin/torchrun", line 6, in <module>
    sys.exit(main())
  File ".../torch/distributed/run.py"
    elastic_launch(...)
  File ".../torch/distributed/launcher/api.py"
    return launch_agent(self._config, self._entrypoint, list(args))
  ...
torch.distributed.elastic.multiprocessing.errors.ChildFailedError:

该错误是 torchrun 对子进程内部异常的包装——注意 DDP 使用的是多进程，具体错误原因被隐藏在内层堆栈中，排查难度较大。

3. 定位到 `deepcopy(model)`

进一步追踪 rank0 的详细堆栈，在测试将 deepcopy(model) 单独拎出后，最终确认真正的异常出在 run_train.py 模型保存阶段调用的该深拷贝函数：

_pickle.PickleError: ScriptFunction cannot be pickled

[rank0]: Traceback (most recent call last):
[rank0]:   File "deps/CP-MACE/mace/cli/run_train.py", line 865, in run
[rank0]:     model_to_save = deepcopy(model)
[rank0]:                     ^^^^^^^^^^^^^^^
[rank0]:   File "copy.py", line 172, in deepcopy
[rank0]:     y = _reconstruct(x, memo, *rv)
[rank0]:   File "copy.py", line 271, in _reconstruct
[rank0]:     state = deepcopy(state, memo)
[rank0]:   File "copy.py", line 231, in _deepcopy_dict
[rank0]:     y[deepcopy(key, memo)] = deepcopy(value, memo)
              ...（递归遍历模型 __dict__）...
[rank0]:   File "torch/jit/_script.py", line 71, in _reduce
[rank0]:     raise pickle.PickleError("ScriptFunction cannot be pickled")

根因分析

`@compile_mode("script")` 与 e3nn codegen

CP-MACE 的模型类及其子模块使用了 e3nn 的 @compile_mode("script") 装饰器：

# deps/CP-MACE/mace/modules/models.py

@compile_mode("script")       # line 111
class MACE(torch.nn.Module):
    ...

@compile_mode("script")       # line 418
class ScaleShiftMACE(MACE):
    ...

当 e3nn 的 jit_script_fx 优化选项处于启用状态（默认行为）时，模型在实例化过程中会通过 e3nn codegen 将部分方法编译为 torch.jit.ScriptFunction 对象。

为何 `deepcopy` 失败

Python 的 copy.deepcopy() 内部依赖 pickle 协议进行序列化。而 torch.jit.ScriptFunction 显式禁止了 pickle：

# torch/jit/_script.py
def _reduce(self):
    raise pickle.PickleError("ScriptFunction cannot be pickled")

因此，当模型内部包含 ScriptFunction 对象时，deepcopy(model) 必然失败。

故障链

模型实例化（e3nn codegen 默认启用）
  → @compile_mode("script") 使模型内部生成 ScriptFunction 对象
    → 训练正常完成，进入保存阶段
      → deepcopy(model) 被调用，试图创建模型副本
        → deepcopy 递归遍历模型 __dict__
          → 遇到 ScriptFunction，触发 pickle 序列化
            → ScriptFunction._reduce() 抛出 PickleError
              → 异常未被捕获，rank0 进程崩溃
                → torchrun 抛出 ChildFailedError

修复方案

核心思路

不使用 deepcopy，而是在 e3nn codegen 关闭的上下文中重新构建一个不含 ScriptFunction 的干净模型，再通过 load_state_dict() 加载训练好的权重。

e3nn 提供了 disable_e3nn_codegen() 上下文管理器（位于 mace/tools/compile.py），在该上下文中创建的模型不会生成 ScriptFunction 对象：

# mace/tools/compile.py
@contextmanager
def disable_e3nn_codegen():
    init_val = get_optimization_defaults()["jit_script_fx"]
    set_optimization_defaults(jit_script_fx=False)
    yield
    set_optimization_defaults(jit_script_fx=init_val)

修改文件

deps/CP-MACE/mace/cli/run_train.py，模型保存阶段（for swa_eval in swas: 循环内，if rank == 0: 分支）。

修改前（原始代码）

        if rank == 0:
            # Save entire model
            if swa_eval:
                model_path = Path(args.checkpoints_dir) / (tag + "_stagetwo.model")
            else:
                model_path = Path(args.checkpoints_dir) / (tag + ".model")
            logging.info(f"Saving model to {model_path}")
            model_to_save = deepcopy(model)          # ← 此处崩溃
            if args.enable_cueq:
                model_to_save = run_cueq_to_e3nn(deepcopy(model), device=device)

修改后

        if rank == 0:
            # 在 e3nn codegen 关闭的上下文中重建模型，避免生成 ScriptFunction
            with disable_e3nn_codegen():
                model_to_save, _ = configure_model(
                    args, train_loader, atomic_energies,
                    model_foundation, heads, z_table,
                )
            model_to_save.to(device)
            model_to_save.load_state_dict(model.state_dict())

            # Save entire model
            if swa_eval:
                model_path = Path(args.checkpoints_dir) / (tag + "_stagetwo.model")
            else:
                model_path = Path(args.checkpoints_dir) / (tag + ".model")
            logging.info(f"Saving model to {model_path}")
            if args.enable_cueq:
                model_to_save = run_cueq_to_e3nn(model_to_save, device=device)

修改要点

#	修改内容	说明
1	移除 `model_to_save = deepcopy(model)`	不再对含有 `ScriptFunction` 的模型做深拷贝
2	新增 `disable_e3nn_codegen()` + `configure_model()`	重建一个结构相同但不含 `ScriptFunction` 的干净模型
3	新增 `load_state_dict(model.state_dict())`	将训练好的参数从原模型复制到新模型
4	CUEQ 转换改用 `model_to_save`	新模型已是独立副本，无需再 `deepcopy`

附录：涉及 `@compile_mode("script")` 的类

以下所有类在 e3nn codegen 启用时均会在实例化过程中产生 ScriptFunction，均可能受此问题影响：

模型层（mace/modules/models.py）：

MACE、ScaleShiftMACE、AtomicDipolesMACE、EnergyDipolesMACE

构建模块（mace/modules/blocks.py）：

LinearNodeEmbeddingBlock、LinearReadoutBlock、NonLinearReadoutBlock、LinearDipoleReadoutBlock、NonLinearDipoleReadoutBlock、AtomicEnergiesBlock、RadialEmbeddingBlock、EquivariantProductBasisBlock、InteractionBlock、TensorProductWeightsBlock 等共 19 个 Block 类

径向基函数（mace/modules/radial.py）：

BesselBasis、ChebychevBasis、GaussianBasis、PolynomialCutoff、ZBLBasis、AgnesiTransform、SoftTransform

宝塔使用Cloudflare API Token部署ACME

Mon, 09 Mar 2026 00:00:00 GMT

1. 项目简介

宝塔面板当前内置的 Let's Encrypt DNS 验证方式，目前11版本依旧只能使用 Cloudflare Global API Key作为DNS解析管理的令牌。私以为该方案权限过大，不利于最小权限控制。

本项目通过 Cloudflare API Token + ACME DNS-01 自动签发证书，并调用宝塔 API 自动部署到指定站点。

核心特点如下：

使用 Cloudflare API Token，避免使用高权限 Global API Key。
通过宝塔 API 读取站点 SSL 信息并自动更新证书。
主进程采用信号触发机制，未触发时 signal.pause() 深度休眠，几乎不消耗 CPU。
证书更新在子进程执行，支持超时强制回收，避免卡死。
验证当前证书是否受信任 CA 签发，异常证书可自动重签。

2. 实现原理

脚本运行后会启动守护进程并写入 update_ssl.pid。平时不主动执行续签，只有收到 SIGUSR1 信号时才触发一次更新流程：

调用宝塔接口获取站点 SSL 信息。
判断是否需要续签：
- 如果当前证书不受信任，则直接重签。
- 如果证书受信任，则在到期前 30 天内进入续签窗口。
使用 ACME + Cloudflare DNS-01 签发新证书。
调用宝塔接口部署证书。
恢复休眠，等待下一次信号触发。

3. 部署前准备

3.1 获取宝塔 API 信息

进入 宝塔面板 -> 面板设置 -> API接口，开启 API 后准备以下信息：

BT_KEY：API 密钥。
BT_PANEL：API 地址，建议使用本机地址，例如 https://127.0.0.1:8888（按实际端口替换）。

建议将 API 白名单限制为 127.0.0.1。

3.2 准备 Cloudflare Token

创建 Cloudflare API Token，至少包含：

Zone -> DNS -> Edit
Zone -> Zone -> Read

Token 仅授权目标 Zone，避免过大权限。

可参考教程：

Cloudflare API Token 获取说明：https://zhuanlan.zhihu.com/p/1918449030331073934

3.3 上传项目文件

在宝塔文件管理中创建项目目录，创建并编辑以下文件：

update_ssl.py
requirements.txt

requirements.txt 内容如下：

acme==5.3.1
certifi==2026.2.25
dnspython==2.7.0
josepy==2.2.0
pyOpenSSL==25.3.0
python-dotenv==1.2.2
requests==2.32.5

update_ssl.py 内容如下：

import hashlib
import json
import logging
import logging.handlers
import multiprocessing
import os
import re
import signal
import ssl
import sys
import time
from datetime import datetime, timedelta

import certifi
import dns.resolver
import josepy as jose
import requests
from dotenv import load_dotenv

load_dotenv()
from acme import challenges, client as acme_client, crypto_util, messages
from cryptography.hazmat.backends import default_backend
from cryptography.hazmat.primitives import serialization
from cryptography.hazmat.primitives.asymmetric import rsa
from OpenSSL import crypto as openssl_crypto

# ========================= 日志配置 =========================

LOG_TO_FILE = os.environ.get("LOG_TO_FILE", "false").lower() in ("true", "1", "yes")
LOG_FILE = os.environ.get(
    "LOG_FILE",
    os.path.join(os.path.dirname(os.path.abspath(__file__)), "update_ssl.log"),
)

logger = logging.getLogger("update_ssl")
logger.setLevel(logging.DEBUG)

if LOG_TO_FILE:
    _file_handler = logging.handlers.RotatingFileHandler(
        LOG_FILE, maxBytes=5 * 1024 * 1024, backupCount=1, encoding="utf-8"
    )
    _file_handler.setLevel(logging.DEBUG)
    _file_handler.setFormatter(
        logging.Formatter("%(asctime)s [%(levelname)s] %(message)s", datefmt="%Y-%m-%d %H:%M:%S")
    )
    logger.addHandler(_file_handler)

_console_handler = logging.StreamHandler()
_console_handler.setLevel(logging.INFO)
_console_handler.setFormatter(
    logging.Formatter("[%(levelname)s] %(message)s")
)
logger.addHandler(_console_handler)

# ========================= 配置变量（从环境变量读取） =========================

def _require_env(name):
    """读取必需的环境变量，缺失则报错退出"""
    val = os.environ.get(name)
    if not val:
        logger.error(f"缺少必需的环境变量: {name}")
        sys.exit(1)
    return val

# 宝塔面板配置
BT_KEY = _require_env("BT_KEY")
BT_PANEL = _require_env("BT_PANEL")

# 站点名称（宝塔面板中的站点标识）
SITE_NAME = _require_env("SITE_NAME")

# Cloudflare 配置
CF_API = os.environ.get("CF_API", "https://api.cloudflare.com/client/v4")
CF_API_TOKEN = _require_env("CF_API_TOKEN")
CF_ZONE_NAME = _require_env("CF_ZONE_NAME")
CF_RECORD_NAME = _require_env("CF_RECORD_NAME")

# ACME (Let's Encrypt) 配置
ACME_DIRECTORY_URL = os.environ.get("ACME_DIRECTORY_URL", "https://acme-v02.api.letsencrypt.org/directory")
ACME_EMAIL = os.environ.get("ACME_EMAIL", "test@message.com")

# 子进程超时（秒），默认5分钟
CHILD_TIMEOUT = int(os.environ.get("CHILD_TIMEOUT", "300"))

# 证书续签配置
RENEW_DAYS_BEFORE = 30
DNS_PROPAGATION_TIMEOUT = 120
DNS_CHECK_INTERVAL = 10
DNS_NAMESERVERS = ["223.5.5.5", "8.8.8.8"] # 阿里DNS和Google DNS

# ========================= 宝塔 API 类 =========================


class BtApi:
    def __init__(self, bt_panel, bt_key):
        self.__BT_PANEL = bt_panel
        self.__BT_KEY = bt_key

    def __get_md5(self, s):
        m = hashlib.md5()
        m.update(s.encode("utf-8"))
        return m.hexdigest()

    def __get_key_data(self):
        now_time = int(time.time())
        p_data = {
            "request_token": self.__get_md5(
                str(now_time) + "" + self.__get_md5(self.__BT_KEY)
            ),
            "request_time": now_time,
        }
        return p_data

    def __http_post_cookie(self, url, p_data, timeout=1800):
        import http.cookiejar
        import urllib.request

        cookie_file = "./" + self.__get_md5(self.__BT_PANEL) + ".cookie"
        cookie_obj = http.cookiejar.MozillaCookieJar(cookie_file)
        if os.path.exists(cookie_file):
            cookie_obj.load(cookie_file, ignore_discard=True, ignore_expires=True)

        # 忽略SSL证书验证（宝塔面板自签名证书）
        ctx = ssl.create_default_context()
        ctx.check_hostname = False
        ctx.verify_mode = ssl.CERT_NONE
        handler = urllib.request.HTTPCookieProcessor(cookie_obj)
        https_handler = urllib.request.HTTPSHandler(context=ctx)

        data = urllib.parse.urlencode(p_data).encode("utf-8")
        req = urllib.request.Request(url, data)
        opener = urllib.request.build_opener(handler, https_handler)
        response = opener.open(req, timeout=timeout)
        cookie_obj.save(ignore_discard=True, ignore_expires=True)
        result = response.read()
        if isinstance(result, bytes):
            result = result.decode("utf-8")
        return result

    def get_ssl(self, site_name):
        """获取站点SSL信息"""
        url = self.__BT_PANEL + "/site?action=GetSSL"
        p_data = self.__get_key_data()
        p_data["siteName"] = site_name
        result = self.__http_post_cookie(url, p_data)
        return json.loads(result)

    def set_ssl(self, site_name, key, csr):
        """设置站点SSL证书"""
        url = self.__BT_PANEL + "/site?action=SetSSL"
        p_data = self.__get_key_data()
        p_data["type"] = -1
        p_data["siteName"] = site_name
        p_data["key"] = key
        p_data["csr"] = csr
        result = self.__http_post_cookie(url, p_data)
        return json.loads(result)


# ========================= 证书验证 =========================


def verify_cert_trusted(cert_pem):
    """
    使用 certifi CA 库验证证书是否由权威机构颁发。
    cert_pem 可能包含 fullchain（叶子证书 + 中间证书）。
    返回 True 表示受信任，False 表示不受信任。
    """
    # 加载 CA 证书库
    store = openssl_crypto.X509Store()
    with open(certifi.where(), "r") as f:
        ca_bundle = f.read()
    ca_pems = re.findall(
        r"-----BEGIN CERTIFICATE-----.*?-----END CERTIFICATE-----",
        ca_bundle,
        re.DOTALL,
    )
    for ca_pem in ca_pems:
        try:
            ca_cert = openssl_crypto.load_certificate(
                openssl_crypto.FILETYPE_PEM, ca_pem
            )
            store.add_cert(ca_cert)
        except openssl_crypto.Error:
            pass

    # 从 cert_pem 中提取叶子和中间证书
    all_certs_pem = re.findall(
        r"-----BEGIN CERTIFICATE-----.*?-----END CERTIFICATE-----",
        cert_pem,
        re.DOTALL,
    )
    if not all_certs_pem:
        return False

    # 第一个是叶子证书，其余是中间证书
    leaf_cert = openssl_crypto.load_certificate(
        openssl_crypto.FILETYPE_PEM, all_certs_pem[0]
    )
    intermediate_certs = []
    for ic_pem in all_certs_pem[1:]:
        intermediate_certs.append(
            openssl_crypto.load_certificate(openssl_crypto.FILETYPE_PEM, ic_pem)
        )

    # 验证时提供中间证书链
    store_ctx = openssl_crypto.X509StoreContext(
        store, leaf_cert, intermediate_certs
    )
    try:
        store_ctx.verify_certificate()
        return True
    except openssl_crypto.X509StoreContextError:
        return False


# ========================= Cloudflare DNS =========================


def cf_headers():
    """返回 Cloudflare API 请求头"""
    return {
        "Authorization": f"Bearer {CF_API_TOKEN}",
        "Content-Type": "application/json",
    }


def cf_get_zone_id():
    """获取 Cloudflare Zone ID"""
    resp = requests.get(
        f"{CF_API}/zones",
        params={"name": CF_ZONE_NAME},
        headers=cf_headers(),
    )
    resp.raise_for_status()
    data = resp.json()
    if not data.get("result"):
        raise RuntimeError(f"未找到 Zone: {CF_ZONE_NAME}")
    return data["result"][0]["id"]


def cf_create_txt_record(zone_id, record_name, value):
    """在 Cloudflare 创建 TXT 记录，返回记录 ID"""
    payload = {"type": "TXT", "name": record_name, "content": value, "ttl": 120}
    resp = requests.post(
        f"{CF_API}/zones/{zone_id}/dns_records",
        json=payload,
        headers=cf_headers(),
    )
    resp.raise_for_status()
    result = resp.json()
    if not result.get("success"):
        raise RuntimeError(f"创建 TXT 记录失败: {result.get('errors')}")
    return result["result"]["id"]


def cf_delete_txt_record(zone_id, record_id):
    """删除 Cloudflare TXT 记录"""
    resp = requests.delete(
        f"{CF_API}/zones/{zone_id}/dns_records/{record_id}",
        headers=cf_headers(),
    )
    resp.raise_for_status()


# ========================= ACME 证书签发 =========================


def generate_account_key():
    """每次运行时生成新的 ACME 账户密钥，返回 josepy.JWKRSA"""
    logger.info("生成 ACME 账户密钥...")
    private_key = rsa.generate_private_key(
        public_exponent=65537, key_size=2048, backend=default_backend()
    )
    return jose.JWKRSA(key=private_key)


def wait_for_dns_propagation(record_name, expected_value):
    """等待 DNS TXT 记录传播，使用公共 DNS 服务器检查"""
    logger.info(
        f"等待 DNS 传播: {record_name} -> {expected_value[:20]}..."
    )
    resolver = dns.resolver.Resolver()
    resolver.nameservers = DNS_NAMESERVERS

    start = time.time()
    while time.time() - start < DNS_PROPAGATION_TIMEOUT:
        try:
            answers = resolver.resolve(record_name, "TXT")
            for rdata in answers:
                for txt_string in rdata.strings:
                    if txt_string.decode("utf-8") == expected_value:
                        elapsed = int(time.time() - start)
                        logger.info(f"DNS 传播完成 (耗时 {elapsed}s)")
                        return True
        except (
            dns.resolver.NXDOMAIN,
            dns.resolver.NoAnswer,
            dns.resolver.NoNameservers,
            dns.exception.Timeout,
        ):
            pass
        time.sleep(DNS_CHECK_INTERVAL)

    logger.warning(f"DNS 传播超时 ({DNS_PROPAGATION_TIMEOUT}s)，继续尝试验证...")
    return False


def issue_certificate(domain):
    """
    使用 ACME 协议通过 Cloudflare DNS 验证签发证书。
    返回 (private_key_pem: str, fullchain_pem: str)，失败返回 (None, None)。
    """
    # 1. 加载/创建账户密钥
    account_key = generate_account_key()

    # 2. 创建 ACME 客户端
    logger.info(f"连接 ACME 服务器: {ACME_DIRECTORY_URL}")
    net = acme_client.ClientNetwork(account_key, user_agent="bt-update-ssl/1.0")
    directory = messages.Directory.from_json(
        net.get(ACME_DIRECTORY_URL).json()
    )
    acme = acme_client.ClientV2(directory, net=net)

    # 3. 注册/获取账户
    logger.info(f"注册 ACME 账户 (邮箱: {ACME_EMAIL})...")
    registration = messages.NewRegistration.from_data(
        terms_of_service_agreed=True, email=ACME_EMAIL
    )
    try:
        acme.new_account(registration)
    except Exception as e:
        # 账户可能已存在，尝试获取
        if "already" in str(e).lower() or "conflict" in str(e).lower():
            logger.info("ACME 账户已存在，继续使用")
        else:
            raise
    logger.info("ACME 账户就绪")

    # 4. 生成证书私钥和 CSR
    logger.info(f"为域名 {domain} 生成私钥和 CSR...")
    private_key = rsa.generate_private_key(
        public_exponent=65537, key_size=2048, backend=default_backend()
    )
    private_key_pem = private_key.private_bytes(
        encoding=serialization.Encoding.PEM,
        format=serialization.PrivateFormat.TraditionalOpenSSL,
        encryption_algorithm=serialization.NoEncryption(),
    )
    csr_pem = crypto_util.make_csr(private_key_pem, [domain])

    # 5. 创建证书订单
    logger.info("创建证书订单...")
    order = acme.new_order(csr_pem)

    # 6. 处理 DNS-01 验证
    zone_id = cf_get_zone_id()
    created_records = []  # 记录创建的 DNS 记录以便清理

    try:
        for authz in order.authorizations:
            authz_domain = authz.body.identifier.value
            logger.info(f"处理域名验证: {authz_domain}")

            # 查找 DNS-01 挑战
            dns01_chall = None
            for chall_body in authz.body.challenges:
                if isinstance(chall_body.chall, challenges.DNS01):
                    dns01_chall = chall_body
                    break

            if dns01_chall is None:
                raise RuntimeError(
                    f"未找到 DNS-01 验证方式: {authz_domain}"
                )

            # 获取验证值
            response, validation = dns01_chall.response_and_validation(
                account_key
            )
            txt_record_name = dns01_chall.chall.validation_domain_name(
                authz_domain
            )

            # 在 Cloudflare 创建 TXT 记录
            logger.info(
                f"创建 DNS TXT 记录: {txt_record_name} = {validation}"
            )
            record_id = cf_create_txt_record(zone_id, txt_record_name, validation)
            created_records.append(record_id)

            # 等待 DNS 传播
            wait_for_dns_propagation(txt_record_name, validation)

            # 通知 ACME 服务器验证
            logger.info("通知 ACME 服务器进行验证...")
            acme.answer_challenge(dns01_chall, response)

        # 7. 等待并完成订单
        logger.info("等待 ACME 服务器完成验证并签发证书...")
        deadline = datetime.now() + timedelta(seconds=240)
        finalized_order = acme.poll_and_finalize(order, deadline=deadline)

        fullchain_pem = finalized_order.fullchain_pem
        key_str = private_key_pem.decode("utf-8") if isinstance(
            private_key_pem, bytes
        ) else private_key_pem

        logger.info("证书签发成功！")
        return key_str, fullchain_pem

    except Exception as e:
        logger.error(f"证书签发失败: {type(e).__name__}: {e}")
        return None, None

    finally:
        # 清理 DNS 记录
        for record_id in created_records:
            try:
                logger.info(f"清理 DNS TXT 记录: {record_id}")
                cf_delete_txt_record(zone_id, record_id)
            except Exception as e:
                logger.warning(f"清理 DNS 记录失败: {type(e).__name__}: {e}")


# ========================= 证书更新逻辑 =========================


def update_certificate():
    """完整的证书检查与更新流程（在子进程中执行）"""
    try:
        _do_update_certificate()
    except Exception as e:
        logger.error(f"无法处理的异常: {type(e).__name__}: {e}", exc_info=True)


def _do_update_certificate():
    """证书更新的具体实现"""
    bt = BtApi(BT_PANEL, BT_KEY)

    # --- 获取当前SSL信息 ---
    logger.info(f"获取站点 {SITE_NAME} 的SSL信息...")
    try:
        ssl_info = bt.get_ssl(SITE_NAME)
    except Exception as e:
        logger.error(f"获取SSL信息异常: {type(e).__name__}: {e}, 请检查宝塔面板连接和站点名称是否正确")
        return

    # 步骤0: 如果 status 为 false，exit 0
    if not ssl_info.get("status", False):
        logger.info("SSL状态为false，退出")
        return

    # 步骤1: 如果 cert_data 为空，exit 0
    cert_data = ssl_info.get("cert_data")
    if not cert_data:
        logger.info("cert_data为空，退出")
        return

    # 步骤2: 验证当前证书是否由权威机构颁发
    cert_pem = ssl_info.get("csr", "")
    need_renew = False

    if cert_pem:
        try:
            trusted = verify_cert_trusted(cert_pem)
        except Exception as e:
            logger.error(f"证书验证异常: {type(e).__name__}: {e}")
            trusted = False
        if not trusted:
            logger.warning("当前证书不受信任（非权威CA颁发），需要重新签发")
            need_renew = True

    # 步骤3: 如果证书受信任，检查是否需要续签
    if not need_renew:
        not_after_str = cert_data.get("notAfter", "")
        if not_after_str:
            not_after = datetime.strptime(not_after_str, "%Y-%m-%d")
            renew_date = not_after - timedelta(days=RENEW_DAYS_BEFORE)
            today = datetime.now()

            if today < renew_date:
                days_left = (not_after - today).days
                logger.info(
                    f"证书有效期至 {not_after_str}，距到期还有 {days_left} 天，"
                    f"续签阈值为到期前 {RENEW_DAYS_BEFORE} 天，无需续签"
                )
                return
            else:
                logger.info(
                    f"证书将于 {not_after_str} 到期，已进入续签窗口，开始续签"
                )
                need_renew = True

    if not need_renew:
        logger.info("无需续签")
        return

    # 步骤4-5: 使用 ACME 签发证书
    logger.info(f"域名: {CF_RECORD_NAME}")
    key, fullchain = issue_certificate(CF_RECORD_NAME)

    if not key or not fullchain:
        logger.error("证书签发失败")
        return

    # 步骤6: 将证书写入宝塔面板
    logger.info(f"正在将证书部署到站点 {SITE_NAME}...")
    try:
        result = bt.set_ssl(SITE_NAME, key, fullchain)
    except Exception as e:
        logger.error(f"部署证书异常: {type(e).__name__}: {e}")
        return

    if result.get("status"):
        logger.info(f"证书部署成功: {result.get('msg', '')}")
    else:
        logger.error(f"证书部署失败: {result.get('msg', '未知错误')}")


# ========================= 守护进程主逻辑 =========================


def main():
    child_proc = None
    should_update = False

    def handle_sigusr1(signum, frame):
        nonlocal should_update
        should_update = True

    def handle_sigterm(signum, frame):
        """收到 SIGTERM/SIGINT 时退出"""
        nonlocal child_proc
        logger.info("收到退出信号，正在退出...")
        if child_proc and child_proc.is_alive():
            child_proc.terminate()
            child_proc.join(timeout=10)
            if child_proc.is_alive():
                child_proc.kill()
        # 删除 PID 文件
        if os.path.exists(pid_file):
            os.unlink(pid_file)
        sys.exit(0)

    # 注册信号
    signal.signal(signal.SIGUSR1, handle_sigusr1)
    signal.signal(signal.SIGTERM, handle_sigterm)
    signal.signal(signal.SIGINT, handle_sigterm)

    # 写入 PID 文件
    pid_file = os.path.join(os.path.dirname(os.path.abspath(__file__)), "update_ssl.pid")
    with open(pid_file, "w") as f:
        f.write(str(os.getpid()))

    logger.info("=" * 30)
    logger.info(f"守护进程已启动，PID: {os.getpid()}")
    logger.info(f"启动时间: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
    logger.info(f"PID 文件: {pid_file}")
    logger.info(f"日志文件: {LOG_FILE}")
    logger.info(f"发送 SIGUSR1 触发证书更新: kill -USR1 $(cat {pid_file})")
    logger.info(f"子进程超时: {CHILD_TIMEOUT}s")

    while True:
        should_update = False

        # 休眠，等待系统中断信号唤醒
        signal.pause()

        if not should_update:
            continue

        # 启动子进程执行更新
        logger.info("收到 SIGUSR1，启动子进程执行证书更新...")
        child_proc = multiprocessing.Process(
            target=update_certificate, daemon=True
        )
        child_proc.start()

        # 等待子进程完成（期间忽略 SIGUSR1）
        child_proc.join(timeout=CHILD_TIMEOUT)

        if child_proc.is_alive():
            logger.warning(f"子进程超时 ({CHILD_TIMEOUT}s)，强制终止")
            child_proc.terminate()
            child_proc.join(timeout=5)
            if child_proc.is_alive():
                child_proc.kill()
                child_proc.join()

        exit_code = child_proc.exitcode
        if exit_code == 0:
            logger.info("子进程正常完成")
        else:
            logger.warning(f"子进程退出码: {exit_code}")

        child_proc = None
        should_update = False
        logger.info("恢复休眠，等待下次信号...")


if __name__ == "__main__":
    main()

3.4 准备 `SITE_NAME`

SITE_NAME 必须与宝塔 API 中站点标识一致，不等同于域名。

推荐获取方式：

打开目标站点 SSL 设置页面。
按 F12 打开开发者工具，切换到“网络”。
在页面点击一次 SSL，观察请求 /site?action=GetSSL 中 负载 的 siteName。
将该值填入环境变量 SITE_NAME。

4. 在宝塔中部署 Python 服务

4.1 创建 Python 项目

进入 网站 -> Python项目 -> 添加项目，建议配置：

项目路径：update_ssl.py 所在目录。
Python 版本：建议 3.13.3（若无可先安装）。
虚拟环境：新建即可，名称自定义。
启动命令：python3 update_ssl.py
启动用户：建议使用普通用户；使用 www 也可运行。
安装依赖：选择 requirements.txt。

4.2 配置环境变量

在 Python 项目环境变量中配置（见第 8 章完整说明）。最少需要填写：

BT_KEY=你的宝塔API密钥
BT_PANEL=https://127.0.0.1:你的宝塔端口
SITE_NAME=宝塔站点标识siteName
CF_API_TOKEN=Cloudflare API Token
CF_ZONE_NAME=主域名，例如example.com
CF_RECORD_NAME=签发证书的完整域名，例如www.example.com

4.3 启动项目

启动 Python 项目后，脚本会写入 PID 文件：

<项目目录>/update_ssl.pid

后续计划任务通过该 PID 文件向主进程发送 SIGUSR1 信号。

4.4 项目日志配置

进入 Python项目 -> 设置 -> 项目日志，建议将日志目录设在项目目录下 logs/。

说明：

默认日志输出到控制台（可在宝塔项目日志查看）。
若需要额外文件日志，请设置 LOG_TO_FILE=true 并配置 LOG_FILE（见第 8 章）。

5. 初始化 SSL 状态（建议）

脚本在读取宝塔 SSL 信息时，若 status=false 或 cert_data 为空会直接退出本次更新。

因此建议先在宝塔给站点配置一张临时证书（可自签），确保 SSL 状态已启用且存在证书数据，然后再交由脚本自动续签替换。

可选参考（自签证书生成工具）：

top.tools：https://tools.top/certificate-generate.html

6. 配置计划任务触发更新

6.1 新建计划任务

进入 计划任务 -> 添加任务 -> Shell脚本，脚本内容如下：

kill -USR1 $(cat /path/to/your/project/update_ssl.pid)

将 /path/to/your/project 替换为实际项目路径。

建议：

任务执行用户与 Python 项目启动用户保持一致。
执行周期按需求设置（例如每天一次）。

6.2 手动执行一次

保存任务后先手动执行一次，确认触发链路正常。

7. 验证部署是否成功

在 网站 -> Python项目 -> 你的项目 -> 设置 -> 项目日志 观察日志。

关键日志示例：

收到 SIGUSR1，启动子进程执行证书更新...
证书签发成功！
证书部署成功: ...
恢复休眠，等待下次信号...

同时到站点 SSL 页面确认新证书是否已自动部署。

8. 环境变量说明（完整）

8.1 必填变量

变量名	说明	示例
`BT_KEY`	宝塔 API 密钥	`xxxx`
`BT_PANEL`	宝塔 API 地址	`https://127.0.0.1:8888`
`SITE_NAME`	宝塔站点标识（`siteName`）	`example.com` 或面板内部标识
`CF_API_TOKEN`	Cloudflare API Token	`xxxx`
`CF_ZONE_NAME`	Cloudflare Zone 名称	`example.com`
`CF_RECORD_NAME`	需要签发证书的完整域名	`www.example.com`

8.2 选填变量

变量名	默认值	说明
`CF_API`	`https://api.cloudflare.com/client/v4`	Cloudflare API 基础地址
`ACME_DIRECTORY_URL`	`https://acme-v02.api.letsencrypt.org/directory`	ACME 目录地址（默认生产环境）
`ACME_EMAIL`	`test@message.com`	ACME 账户邮箱
`CHILD_TIMEOUT`	`300`	子进程超时时间（秒）
`LOG_TO_FILE`	`false`	是否写入文件日志（`true/1/yes` 生效）
`LOG_FILE`	`<项目目录>/update_ssl.log`	文件日志路径

8.3 固定参数（需改代码）

以下参数当前写死在脚本中，如需调整需修改代码：

续签窗口：RENEW_DAYS_BEFORE = 30
DNS 传播超时：DNS_PROPAGATION_TIMEOUT = 120
DNS 查询间隔：DNS_CHECK_INTERVAL = 10
DNS 解析服务器：223.5.5.5、8.8.8.8

9. 常见问题与排查

9.1 定时任务执行但无更新日志

检查 update_ssl.pid 是否存在。
检查 PID 是否对应运行中的 Python 进程。
检查任务用户是否有权限读取 PID 文件并发送信号。

9.2 日志提示缺少环境变量

脚本启动时会校验必填变量，缺失即退出。请逐项核对第 8.1 节。

9.3 Cloudflare 相关报错

检查 Token 权限是否包含 DNS Edit 与 Zone Read。
检查 CF_ZONE_NAME 与实际 Zone 是否一致。
检查 CF_RECORD_NAME 是否属于该 Zone。

9.4 ACME 验证失败

检查 DNS 记录是否成功创建。
检查域名是否正确解析到当前站点。
如 DNS 生效慢，可适当增大 DNS_PROPAGATION_TIMEOUT（改代码）。

9.5 宝塔部署失败

检查 BT_PANEL 地址和端口。
检查 BT_KEY 是否正确。
检查 SITE_NAME 是否准确。

使用我们的Slurm集群

Sun, 01 Mar 2026 00:00:00 GMT

Slurm集群使用指南

欢迎使用本集群。本文档将引导您完成从环境配置到作业提交的完整流程，帮助您高效利用计算资源。

0. 系统架构

集群由六台服务器组成，通过一台 40G 以太网交换机互连，构建高速计算网络。

<!-- ```mermaid graph TD Switch[Mellanox SX6012 40G 交换机]

Login[登录服务器]
GPU["GPU服务器<br/>64c128t | 384GB RAM<br/>8×NVIDIA 4090 48GB"]
CPU1["CPU服务器1<br/>48c96t | 128GB RAM"]
CPU2["CPU服务器2<br/>48c96t | 128GB RAM"]
Storage["存储服务器<br/>48TB 阵列<br/>1TB NVMe SSD 缓存<br/>256GB Optane PMEM"]

Login --- Switch
GPU --- Switch
CPU1 --- Switch
CPU2 --- Switch
Storage --- Switch

-->


**硬件配置明细**：

- **控制服务器**：控制节点，用于作业调度、提供REST API。
- **登录服务器**：用户接入节点，用于作业提交和管理。
- **GPU服务器**：64核心128线程，120GB内存，8张NVIDIA 4090 48GB显卡。
- **CPU服务器1**：48核心96线程，128GB内存。
- **CPU服务器2**：48核心96线程，256GB内存。
- **存储服务器**：48TB硬盘阵列，配备1TB NVMe SSD高速缓存和256GB Intel Optane PMEM超高速缓存。

<img width="1512" height="867" alt="零信任平台入口" src="/posts/usingSlurm/topology.png" />

注意：控制节点和登陆节点是一台mac mini上跑的虚拟机。因此，对于登陆节点，请不要再上面编译程序或者运行代码，基本上编不出来，编出来了你在计算节点上也跑不了~~你要交叉编译那我也没啥好说的~~。

---

## 1. 环境与基本配置

出于安全因素，除SSH，所有的敏感业务访问都必须通过 `Cloudflare 零信任平台` 进行登录，Cloudflare会记录你的用户态，单次有效期最长为24小时。你的密码修改，证书获取，以及查看我们的web面板，都属于敏感业务。

### 1.1 登录零信任平台
访问 [https://ai4qc-hkust.cloudflareaccess.com/](https://ai4qc-hkust.cloudflareaccess.com/)。  
**注意**：必须使用已在 `ai4qc` 组织内的 GitHub 帐户登录，否则无法获得授权。  
成功登录后，您将看到如下界面：  
<img width="1512" height="867" alt="零信任平台入口" src="/posts/usingSlurm/zt-entrypoint.png" />



### 1.2 访问用户管理界面
点击零信任平台中的 **profile** 或直接访问 [https://slurm-profile.thy.icu/](https://slurm-profile.thy.icu/) 进入用户管理界面。  
<img width="1512" height="867" alt="image" src="/posts/usingSlurm/go-ldap-login.png" />


### 1.3 首次登录与初始密码
- 点击 **OAuth 登录**，使用您的 GitHub 账号授权。初次登录将自动完成用户注册。
- 登录成功后进入个人主页。**新用户会弹出初始密码**，请妥善保存；您可以立即修改或暂时忽略。  
<img width="1512" height="867" alt="image" src="/posts/usingSlurm/profile-page.png" />

## 1.4 配置终端（可选）
默认登录 Shell 为 **zsh**，其具备强大的自动补全和主题功能。如需切换为 bash，请在登录后进入 **“终端设置”** → **“Shell”** 进行修改。


### 1.5 获取 SSH 证书
在个人主页中，找到 **“生成并下载 SSH 证书”** 区域，点击 **“生成”** 按钮。系统将生成一对证书并自动下载为一个压缩包：
- **私钥文件**：文件名格式为 `[用户名]-[日期]`（例如 `zhangsan-20250302`）
- **签名证书**：文件名格式为 `[用户名]-[日期]-cert.crt`（例如 `zhangsan-20250302-cert.crt`）

解压后，您可以选择以下任一方式使用证书连接集群：

#### 注意事项
```bash
以防有人不仔细看，SSH 记得加端口9933

1.5.1 使用命令行直接登录

ssh -i /path/to/private_key_file <username>@login.thy.icu -p 9933

（SSH 客户端会自动寻找同名的证书文件，无需额外指定。）

1.5.2 配置 SSH config

在 ~/.ssh/config 中添加如下配置：

Host slurm-login
    HostName login.thy.icu
    User <your-username>
    Port 9933
    IdentityFile /path/to/private_key_file
    CertificateFile /path/to/cert_file
    AddKeysToAgent yes

之后可直接使用 ssh slurm-login 登录。

1.5.3 在 VS Code 中使用

参考官方文档 Improving your security with a dedicated key，配置 Remote-SSH 使用证书。

1.5.4 在 Termius 中使用

Termius 支持直接导入 SSH 证书，请参阅 Import SSH Certificate 完成设置。

2. Slurm 作业调度系统使用

一些基本说明

2.1 分区说明

集群包含两个分区（Partition）：

cpu：用于纯 CPU 计算任务（默认分区）。
gpu：用于 GPU 加速任务。

提交作业时若未指定分区，默认使用 cpu。

2.2 登入登陆节点

进入登陆节点后，会有一些基本的信息提示 <img width="1512" height="867" alt="image" src="/posts/usingSlurm/login-default.png" />
在个人目录下，有个共享文件夹，你可以在这放置共享文件，如协作目录等 <img width="1512" height="867" alt="image" src="/posts/usingSlurm/shared.png" />

共享目录默认的文件权限为 所有人可创建; 文件只有创建者可读写; 他人只读 ，如果需要创建协作目录，建议参考以下命令
```
# 如果协作目录是 你可读写，他人只读
chmod 777 <你的协作目录>
# 如果协作目录下是 所有人可创建; 文件只有创建者可读写，他人只读
chmod 1777 <你的协作目录>
```

2.3 查看集群信息

你可以使用 sinfo 查看节点和分区信息 <img width="1512" height="867" alt="image" src="/posts/usingSlurm/sinfo.png" />
你可以使用 module ava 支持的查看软件包模块 <img width="1512" height="867" alt="image" src="/posts/usingSlurm/module-ava.png" /> 之后，你可以使用module load加载你想要的软件包

2.4 提交作业示例

GPU 作业：系统会自动分配一张显卡。如需多卡，请使用 -G 或 --gres 参数显式指定。

# 自动分配一张显卡（默认）
sbatch -p gpu -c 4 your_program

# 显式指定使用4张显卡
sbatch -p gpu -G 4 --cpus-per-task=4 your_program

CPU 作业：需自行指定核心数量。
```
sbatch -p cpu -c 8 your_program
```

2.5 注意事项

暂无，不要在登陆节点跑重型负载即可

2.6 更多参考

以下页面提供了详尽的 Slurm 使用指南，如有需要强烈建议阅读：

上海交通大学超算平台: Slurm 作业调度系统¶
Slurm Worker Manager: Slurm Documentation
CLab Server Docs: LMod 使用指南
LMod: User Guide for Lmod

3. 任务后台查看

我们有个非常漂亮的后台，以下是它的使用教程

3.1 访问 Dashboard

打开浏览器访问 https://slurm-dashboard.thy.icu/。
若浏览器会话中无有效的 Access Token，系统将自动重定向至 Cloudflare 零信任网关重新登录。认证成功后，将跳转至 Dashboard, 即可查看作业状态、资源使用情况等。

更详细的使用说明，请阅读Slurm-web/Overview <img width="1512" height="867" alt="image" src="/posts/usingSlurm/slurm-web.png" />

4. 传输文件

传输文件支持以下几种方式(可点击超链接跳转教程)：

rsync
SFTP
百度网盘，教程可以忽略前面的"下载"部分，我已经部署好了，直接从 “登录” 开始看即可

5. 密码管理

~~以防你忘记密码了，虽然说这东西没啥用~~

5.1 登录 profile 页面

访问 https://slurm-profile.thy.icu/ 并使用 GitHub OAuth 登录。

5.2 修改密码

在 “修改帐户密码” 区域，您可以通过以下两种方式验证身份：

原密码：输入当前密码。
OAuth：使用 GitHub 快速验证（推荐，邮箱验证暂不可用）。

验证通过后，在右侧输入新密码两次，确保一致，点击提交即可。

5.3 注意事项

密码修改成功后，您会被强制登出，后续访问需使用新密码重新登录。
请妥善保管密码，避免泄露。

如有任何问题，请联系系统管理员。

舞浅静的博客

SSH 远程端口转发无法启动：直接登录正常但隧道卡住

环境

问题

排查过程

1. 观察客户端日志

2. 检查服务器端口占用

3. 清理残留进程

4. 重新尝试隧道

根因分析

正常流程

异常残留

为什么普通登录正常？

附录：脱敏后的完整日志供参考

总结

Slurm NFS 挂载后 IO error 排障记录

背景

故障现象

复现方式

初始检查

尝试不同NFS参数和版本

定位到 MTU

临时验证

交换机修复

最终切回 NFSv4.2

最终验证

总结

MACE多卡训练无法保存模型

环境

问题描述

排查过程

1. 现象：训练完成后崩溃

2. 定位到 DDP 分布式进程异常

3. 定位到 deepcopy(model)

根因分析

@compile_mode("script") 与 e3nn codegen

为何 deepcopy 失败

故障链

修复方案

核心思路

修改文件

修改前（原始代码）

修改后

修改要点

附录：涉及 @compile_mode("script") 的类

宝塔使用Cloudflare API Token部署ACME

目录

1. 项目简介

2. 实现原理

3. 部署前准备

3.1 获取宝塔 API 信息

3.2 准备 Cloudflare Token

3.3 上传项目文件

3.4 准备 SITE_NAME

4. 在宝塔中部署 Python 服务

4.1 创建 Python 项目

4.2 配置环境变量

4.3 启动项目

4.4 项目日志配置

5. 初始化 SSL 状态（建议）

6. 配置计划任务触发更新

6.1 新建计划任务

6.2 手动执行一次

7. 验证部署是否成功

8. 环境变量说明（完整）

8.1 必填变量

8.2 选填变量

8.3 固定参数（需改代码）

9. 常见问题与排查

9.1 定时任务执行但无更新日志

9.2 日志提示缺少环境变量

9.3 Cloudflare 相关报错

9.4 ACME 验证失败

9.5 宝塔部署失败

使用我们的Slurm集群

Slurm集群使用指南

0. 系统架构

1.5.1 使用命令行直接登录

1.5.2 配置 SSH config

1.5.3 在 VS Code 中使用

3. 定位到 `deepcopy(model)`

`@compile_mode("script")` 与 e3nn codegen

为何 `deepcopy` 失败

附录：涉及 `@compile_mode("script")` 的类

3.4 准备 `SITE_NAME`