# 实验室集群使用指南 v0.1

> 使用中遇到问题，请先查阅本指南「常见问题」一节，仍无法解决时联系管理员。

## 0. 账号信息（通过微信单独发送）

开通账号后，您将收到以下三项信息：

- **NetBird setup key**（一次性接入码）
- **用户名**（拼音）
- **初始密码**（首次登录后必须修改）

## 1. 第一次接入（约 10 分钟）

**① 安装 NetBird**

从 [netbird.io/downloads](https://netbird.io/downloads) 下载安装（支持 Windows / macOS / Linux），打开托盘图标，粘贴 setup key，显示 Connected 即接入成功。此后开机自动连接，无需重复操作。

**② 登录集群**

```bash
ssh <用户名>@**        # 具体 IP 请找管理员获取
# 首次登录：输入初始密码后，系统会强制要求设置新密码（请妥善保管，管理员无法查看）
```

**③（推荐）升级为密钥登录**

修改密码后，可申请免密登录：

```bash
ssh-keygen -t ed25519 -f ~/.ssh/lab_key     # 一路回车
cat ~/.ssh/lab_key.pub                       # 将输出的公钥发给管理员
# 管理员配置完成后，即可 ssh -i ~/.ssh/lab_key 免密登录（也可写入 ~/.ssh/config 简化命令）
```

**Windows 用户推荐 VSCode + Remote-SSH 插件**：配置一次后，打开即是集群内的 VSCode，编辑、绘图、终端一体化。

## 2. 目录结构与存储

```
~/ (= /cluster/home/<你的用户名>)   私有空间，配额 200G
├── work/       代码（git clone 或 rsync 上传）
├── results/    作业输出目录
/cluster/software/   公共只读：Julia 环境、sbatch 模板
/cluster/scratch/    公共临时区（每 7 天自动清理，请勿存放重要数据）
```

查询磁盘空间：`df -h ~`

## 3. 提交作业（SLURM，模板位于 /cluster/software/templates/）

```bash
cd ~/work/myproject
cp /cluster/software/templates/julia-basic.sbatch run.sbatch
vim run.sbatch      # 需修改：作业名、邮箱、.jl 文件名
sbatch run.sbatch   # → Submitted batch job 128
```

- **快速测试通道**：`sbatch --qos=test run.sbatch`（限制 4 核 / 30 分钟，自动优先排队，适合小规模验证）
- 模板已内置 `--mail-type=END,FAIL --mail-user=<你的邮箱>`，**请务必将邮箱改为本人邮箱**，作业结束或失败时会自动收到邮件通知

## 4. 日常命令

```bash
squeue -u $USER   # 查看本人作业（PD=排队中，R=运行中）
squeue            # 查看全部队列
scancel <id>      # 取消作业
sacct -j <id>     # 查询历史详情（耗时 / 内存 / 退出码）
```

进阶用法（数组作业、指定节点、内存申请等）见模板目录中的进阶示例，另可参考 [SLURM 官方快速入门](https://slurm.schedmd.com/quickstart.html)。建议逐步掌握，这是使用集群的基础。

## 5. 获取结果

作业输出直接写入`\home`目录，无需专门"收取"：

```bash
ls ~/results/128/         # 128.out 为日志，同目录下为产物文件
rsync -avz <用户名>@**:~/results/128/ ./128/   # IP 找管理员要；将结果拉回本地
```

VSCode Remote 模式下可直接打开或拖拽下载。

## 6. 登录节点测试限制

登录节点（即您 ssh 连接的机器）可用于 `julia test.jl` 级别的小规模验证，**每人限 1 核 / 8G 内存**，超出限额的进程会被系统自动终止。计算量较大的任务请一律通过 sbatch 提交。

## 7. 使用规范

| 规范 | 说明 |
|---|---|
| 限额：200G `\home`目录 / 20 并发作业 / 64G 内存 | 共享资源，如需提升请联系管理员评估 |
| scratch 每 7 天清空 | 临时区，勿存放重要数据 |
| 大结果（>50G）请提前告知管理员 | 以便调整配额 |
| 请及时将代码推送到 git 仓库 | \home目录快照仅保留 7 天，不作为长期备份 |
| 请勿在登录节点运行重度计算 | 见第 6 节 |
| 密码请勿与校内其他系统复用 | 基本安全要求 |

## 8. 常见问题

| 症状 | 处理方法 |
|---|---|
| 连接不上 | 重新检查第 1 节各步骤；仍失败请联系管理员 |
| 作业长时间处于 PD | 用 `squeue` 查看原因列；资源排队属正常现象 |
| 作业失败 | 请先自行查看 `~/results/<id>.out` 日志，多数为代码问题 |
| 磁盘空间不足 | 清理无用文件，或联系管理员 |
| 忘记密码 | 联系管理员重置 |