![Gemini_Generated_Image_on2hn9on2hn9on2h.png](/static/img/98253e178027447a87592df6a5e21be6.Gemini_Generated_Image_on2hn9on2hn9on2h.webp)

备份这事平时没存在感，出事时才知道有没有后悔药。Restic 的加密、去重和增量备份很适合 HomeLab，这里记录一套能长期自动跑的备份方案。



**摘要**：在 HomeLab 数据治理中，如何实现高效、加密且节省空间的“后悔药”机制？本文将详解 Restic 的核心原理，并提供一份生产环境可用的自动化运维脚本，实现 Windows 数据在 Linux 端的增量快照保护。

## 一、 为什么选择 Restic？

在众多的备份工具中，Restic 凭借其**内容寻址存储 (Content-Addressable Storage)** 技术脱颖而出。它不仅仅是复制文件，更像是一个精密的“数据去重引擎”。

* **极致去重 (Deduplication)**：Restic 将文件切碎成加密的数据块（Blob）。无论你把文件改名、移动目录，只要文件内容的指纹（Hash）没变，仓库中就只存储一份数据。
* **增量快照 (Snapshots)**：第二次备份时，Restic 仅需扫描变动的数据块。对于数万个文件，只要内容未变，备份任务耗时仅数秒，且**新增存储占用为 0KB**。
* **原生加密**：所有数据在离开源目录前都会被 AES-256 强制加密，确保备份仓库（即使在不受信任的云端）也是绝对安全的。

## 二、 环境拓扑

本文基于以下 HomeLab 典型场景：

* **数据源**：宿主机 Windows 的 `D:\Software` 目录。
* **备份执行端**：Ubuntu 24.04 虚拟机。
* **连接方式**：通过 VMware HGFS (共享文件夹) 将 Windows 目录挂载至 Linux 的 `/mnt/hgfs/Software`。

## 三、 部署与初始化

### 1. 安装 Restic

在 Ubuntu/Debian 系统中，安装非常简单：

```bash
sudo apt update
sudo apt install restic -y

```

### 2. 初始化仓库 (Repository)

我们需要创建一个目录作为“保险箱”（Repository）。这个目录可以是本地磁盘，也可以是挂载的 NAS 路径。

```bash
# 1. 创建仓库目录
mkdir -p /home/user/backup_repo

# 2. 初始化仓库
# ⚠️ 注意：执行后会要求设置密码。丢失密码意味着数据永久丢失，请务必记牢！
restic init --repo /home/user/backup_repo

```

## 四、 自动化运维脚本 (核心实操)

为了实现“无人值守”备份，我们需要编写一个 Shell 脚本，封装**挂载检查、自动备份、日志记录、旧快照清理**的全流程。

### 1. 创建脚本目录

```bash
mkdir -p ~/scripts
cd ~/scripts
nano restic_backup.sh

```

### 2. 写入脚本内容

请复制以下完整代码（已包含生产级环境配置）：

```bash
#!/bin/bash

# ================= 配置区域 =================
# 1. Restic 仓库位置
export RESTIC_REPOSITORY="/home/user/backup_repo"

# 2. Restic 仓库密码 (务必修改为你初始化时的密码)
export RESTIC_PASSWORD="your_secure_password"

# 3. 备份源目录 (Windows 挂载点)
BACKUP_SOURCE="/mnt/hgfs/Software"

# 4. 日志文件路径
LOG_FILE="/home/user/scripts/restic_backup.log"

# 5. 保留策略 (保留最近7天，4周，6个月)
KEEP_DAYS=7
KEEP_WEEKS=4
KEEP_MONTHS=6
# ===========================================

# 日志函数
log() {
    echo "[$(date '+%Y-%m-%d %H:%M:%S')] $1" | tee -a "$LOG_FILE"
}

log "====== 备份任务启动 ======"

# Step 1: 环境自检
if ! command -v restic &> /dev/null; then
    log "错误: 未找到 restic 命令，请先安装！"
    exit 1
fi

# Step 2: 挂载检查 (关键防错步骤)
# 防止因共享文件夹断开，导致 Restic 备份了一个空目录，造成数据“被清空”的假象
if [ -z "$(ls -A "$BACKUP_SOURCE" 2>/dev/null)" ]; then
    log "严重错误: 源目录 $BACKUP_SOURCE 为空或未挂载！任务终止。"
    exit 1
fi

# Step 3: 执行增量备份
log "正在备份 $BACKUP_SOURCE ..."
# --verbose: 输出详细信息
restic backup "$BACKUP_SOURCE" --verbose >> "$LOG_FILE" 2>&1
BACKUP_STATUS=$?

if [ $BACKUP_STATUS -eq 0 ]; then
    log "✅ 备份成功！"
else
    log "❌ 备份失败！错误码: $BACKUP_STATUS"
    exit 1
fi

# Step 4: 自动修剪 (Forget & Prune)
# 根据策略清理过期的旧快照，释放空间
log "正在清理旧快照..."
restic forget --keep-daily $KEEP_DAYS --keep-weekly $KEEP_WEEKS --keep-monthly $KEEP_MONTHS --prune >> "$LOG_FILE" 2>&1

log "====== 备份任务结束 ======"
echo "---------------------------------------------------" >> "$LOG_FILE"

```

### 3. 赋予执行权限与格式清洗

**特别注意**：如果你是在 Windows 下复制的代码，一定要执行 `sed` 命令去除可能存在的 Windows 换行符。

```bash
# 赋予执行权限
chmod +x restic_backup.sh

# 清洗 Windows 换行符 (\r)
sed -i 's/\r$//' restic_backup.sh

```

### 4. 手动测试

```bash
./restic_backup.sh

```

如果输出 `✅ 备份成功！`，说明脚本运行正常。

## 五、 设置定时任务 (Crontab)

让脚本每天凌晨自动运行，彻底解放双手。

1. 编辑 Crontab 配置：
```bash
crontab -e

```


2. 添加如下规则（每天凌晨 02:00 执行）：
```bash
0 2 * * * /home/user/scripts/restic_backup.sh

```



## 六、 常用维护命令速查

备份只是手段，恢复才是目的。以下是 Restic 的常用“后悔药”指令：

* **查看所有快照**：
```bash
restic -r /home/user/backup_repo snapshots

```


* **查看仓库占用了多少空间**：
```bash
restic -r /home/user/backup_repo stats

```


* **恢复指定快照**：
```bash
# 将快照 ID (如 a1b2c3d4) 恢复到 /tmp/restore 目录
restic -r /home/user/backup_repo restore a1b2c3d4 --target /tmp/restore

```



## 七、 进阶体验：Windows 下的“可视化”时光机 (Restic Browser)

命令行适合机器自动跑，但人眼看数据还是图形化界面更亲切。为了在 Windows 上像浏览资源管理器一样查看 Linux 里的备份快照，我们需要用到开源神器 —— **Restic Browser**。

### 1. 工具准备

* **名称**：Restic Browser
* **获取方式**：直接在 GitHub Releases 页面下载 Windows 版的 `.exe` 文件（它是绿色的，无需安装，双击即用）。

### 2. 连接方式 (核心技巧)

由于我们的备份仓库位于 Ubuntu 虚拟机内 (`/home/user/backup_repo`)，而我们在 Windows 上操作，最优雅的方式不是把文件拷出来，而是**通过 SFTP 协议直接读取虚拟机里的仓库**。

**操作步骤**：

1. **打开 Restic Browser**。
2. 点击 **"Select Repository"**。
3. 在连接类型中选择 **"SFTP"** (这需要你的 Ubuntu 开启了 SSH 服务，通常默认开启)。
* **Host**: 输入 Ubuntu 的 IP 地址 (例如 `192.168.x.x`)。
* **Username**: Ubuntu 的登录用户名。
* **Password**: Ubuntu 的登录密码。
* **Path**: 填入仓库绝对路径 `/home/user/backup_repo`。


4. 点击 Connect，系统会提示输入 **Restic 的仓库密码** (初始化时设置的那个)。

### 3. 浏览与恢复 (Restore)

连接成功后，你将看到一个清晰的时间轴列表：

* **Snapshots**: 左侧列出了所有的备份快照，按时间倒序排列。
* **Browsing**: 双击任意一个快照 ID，右侧就会像“资源管理器”一样展示当时的文件目录结构。
* **Restore**:
* 找到你想恢复的文件或文件夹。
* 右键点击 **"Restore to..."**。
* 选择 Windows 本地的一个路径（比如桌面）。
* 进度条跑完，文件就“穿越”回来了。



### 4. 为什么推荐这样做？

* **零干扰**：你不需要在 Windows 上安装 Restic 命令行，也不需要配置复杂的 Samba 共享。
* **只读安全**：Restic Browser 默认以浏览为主，不会误触破坏仓库结构。
* **跨越时空**：配合我们设置的自动脚本，你可以随时在 Windows 上打开这个软件，查看“昨天”、“上周”甚至“半年前”的文件状态，并一键取回。

---

**[技术彩蛋]**
如果你希望不仅能“看”，还能直接把快照挂载成 Windows 的一个 **“Z 盘”**，可以使用 Restic Browser 里的 **"Mount"** 功能（需要预先安装 WinFsp 驱动）。这样，历史备份就像一个本地硬盘一样挂在你的“此电脑”里，体验极佳！

## 总结

通过 Restic，我们构建了一个**加密、去重、可回溯**的数据保险箱。无论是误删文件，还是遭遇勒索病毒，你都可以通过一条命令，将数据“时光倒流”回任意安全的时刻。对于 HomeLab 玩家而言，这是数据安全最坚实的一道防线。

 Restic 自动化增量备份指南

![Gemini_Generated_Image_a4q4gda4q4gda4q4.png](/static/img/cc5b4c7e7ee9ba0437c93bdeefb31fec.Gemini_Generated_Image_a4q4gda4q4gda4q4.webp)

异地访问家里设备，最舒服的状态就是像在同一个局域网里。Tailscale 把 WireGuard 的复杂度藏起来，我这次主要记录它如何把 NAS、云服务器和办公电脑连成一张私有网。



## 第一部分：Tailscale是什么？

### 1.1 技术背景

Tailscale 是一款基于 **WireGuard** 协议的现代 VPN 工具。与传统 VPN（如 OpenVPN）或内网穿透工具（如 Frp）不同，它主打 **Mesh（网状）网络**。

* **传统 VPN：** 所有流量必须经过中心服务器中转，一旦中心挂了，全网瘫痪。
* **Tailscale：** 它是 **P2P（点对点）** 直连的。只要打洞成功，你的手机和家里的 NAS 就是直接通信，速度极快且不依赖中心服务器中转。

### 1.2 核心优势

1. **零配置（Zero Config）：** 无需公网 IP，无需路由器端口映射，无需配置复杂的防火墙。
2. **MagicDNS：** 内网不再是一串难记的 IP（如 `100.64.0.5`），而是直接用机器名互联（如 `http://nas`、`ping laptop`）。
3. **安全性：** 流量全程端到端加密，甚至比直接暴露公网端口更安全。

### 1.3 三大“杀手级”功能

* **全互联：** 手机、电脑、服务器随时随地像在一个局域网里。
* **Exit Node（出口节点）：** 让你的流量“回家”绕一圈再上网（防监听、伪装 IP）。
* **Subnet Router（子网路由）：** 一人得道，鸡犬升天。只要一台机器装了 Tailscale，整个局域网里的打印机、摄像头（没法装软件的设备）都能被远程访问。

---

## 第二部分：部署方案选择 (Script vs Docker)


### 2.1 官方脚本直接安装 (Linux Native)

* **优点：** 简单粗暴，直接运行在宿主机系统层，网络性能理论上损耗最小。
* **缺点：** 污染宿主机环境，升级/卸载/迁移比较麻烦，配置文件分散。

**官方脚本一键安装：**

`curl -fsSL https://tailscale.com/install.sh | sh`

安装完成后，会生成一个地址，复制到浏览器完成登录过程。

![PixPin_2026-01-01_06-12-09.png](/static/img/c19a014d7f966eff47939c89bca3df63.PixPin_2026-01-01_06-12-09.webp)

如果要省去登陆流程，进入此页面申请一个key，生成带有密钥的脚本一键安装：

https://login.tailscale.com/admin/machines/new-linux

### 2.2 Docker Compose 安装 (推荐)

* **优点：**
* **配置即代码 (IaC)：** 所有配置写在一个 `.yml` 文件里，改配置只需改文件。
* **环境隔离：** 不弄乱宿主机的 `/etc` 目录。
* **易管理：** 想要开关某个功能（如 Exit Node），只需修改文件注释，然后重启容器即可。


* **结论：** 对于 NAS用户，**Docker Compose 是最佳实践**。

---

## 第三部分：终极部署指南 (Docker Compose)

这是**“完整版”**配置文件。包含了常用的**状态持久化**、**出口节点**、**子网路由**等功能开关。

### 3.1 准备工作

1. **获取 Auth Key：** 登录 [Tailscale 控制台](https://login.tailscale.com/admin/settings/keys) -> Settings -> Keys -> Generate auth key。
2. **开启 TUN 模块：** 确保宿主机开启了 TUN（大多数 NAS 和 Linux 默认开启，若报错参考之前的修复命令）。

### 3.2 `docker-compose.yml` 模板

```yaml
version: "3.7"
services:
  tailscale:
    container_name: tailscale
    image: tailscale/tailscale:latest
    restart: unless-stopped
    network_mode: host  # 强烈建议使用 host 模式，性能最好且支持 IPv6
    
    # ⚠️ 核心权限：必须赋予网络管理权限，否则无法建立 VPN 隧道
    cap_add:
      - NET_ADMIN
      - NET_RAW
    
    volumes:
      # 1. 数据持久化：防止重启容器后 IP 变化 (左边路径改为你的实际路径)
      - ./data/var_lib:/var/lib
      # 2. 核心设备映射：必须映射宿主机的 /dev/net/tun
      - /dev/net/tun:/dev/net/tun
    
    environment:
      # 1. 认证密钥 (填入后首次启动自动登录)
      - TS_AUTHKEY=tskey-auth-xxxxxxxxx
      
      # 2. 主机名 (MagicDNS 里的名字)
      - TS_HOSTNAME=nas-server
      
      # 3. 状态目录 (配合上面的 volumes 使用)
      - TS_STATE_DIR=/var/lib
      
      # ================= 功能开关区 (按需取消注释) =================
      
      # 【功能 A：出口节点 Exit Node】
      # 开启后，这台机器变成“VPN服务器”，允许其他设备通过它上网
      - TS_EXTRA_ARGS=--advertise-exit-node

      # 【功能 B：子网路由 Subnet Router】
      # 允许远程访问家里没装 Tailscale 的设备 (如 192.168.1.1 路由器后台)
      # 请将 192.168.x.x/24 修改为你家局域网的实际网段
      # - TS_ROUTES=192.168.1.0/24,192.168.100.0/24
      
      # 【功能 C：用户态网络模式】
      # 如果 network_mode: host 报错，可以使用这个，但性能稍差
      # - TS_USERSPACE=true

```

### 3.3 启动与修改配置

* **启动：** `docker-compose up -d`
* **修改配置（比如要增加子网路由）：**
1. 用编辑器打开 `docker-compose.yml`。
2. 取消 `TS_ROUTES` 那一行的注释，填入网段。
3. 再次执行 `docker-compose up -d`（Docker 会自动识别变化并重建容器，无需手动停止）。



---

## 第四部分：关键功能解析与使用 (Q&A 汇总)

### 4.1 Exit Node (出口节点) 详解

**Q1：开启后，我在公司的上网行为还会被监控吗？**

* **网络层监控（路由器/防火墙）：** **失效**。公司的网管只能看到你的电脑在和一个 IP（你家 NAS）进行加密通信，看不到你访问了什么网站，也看不到内容。
* **终端层监控（公司电脑上的软件）：** **依然有效**。如果公司在你电脑上装了深信服、360 企业版等监控软件，它们会直接录屏或拦截进程，VPN 救不了你。
* **建议：** 只在**自己的手机/iPad** 连接公司 WiFi 时使用此功能，此时是绝对安全的。

**Q2：对网速影响大吗？**

* **极大**。这是一个“木桶效应”。
* **速度上限 = 你家宽带的上行带宽**。通常家用宽带上行只有 30Mbps (约 3-4MB/s)。
* 这意味着你在公司下载文件的速度不会超过 3MB/s，且延迟会增加（数据要绕路回家）。

**Q3：如何开启？**

1. **服务器端：** 在上面的 `docker-compose.yml` 中添加 `--advertise-exit-node` 并启动。
2. **控制台端：** 登录 Tailscale 网页后台 -> Machines -> 点击 NAS -> Edit route settings -> **勾选 Use as exit node**（这一步必须做，否则不生效）。
3. **客户端（手机/电脑）：** 点击 Tailscale 图标 -> Exit Node -> 选择 `nas-server`。

### 4.2 Subnet Router (子网路由) 详解

**Q：我想远程访问家里的打印机（192.168.1.100），但打印机装不了 Tailscale 怎么办？**

1. **原理：** 只要 NAS 装了 Tailscale 并开启 Subnet Router，它就充当了“网关”。你的手机发送请求给 192.168.1.100，Tailscale 会先把请求传给 NAS，NAS 再转发给打印机。
2. **配置：** 在 `TS_ROUTES` 填入 `192.168.1.0/24`。
3. **控制台审批：** 同样需要在网页后台 Edit route settings 中勾选批准该路由。

Tailscale实现异地组网

![Gemini_Generated_Image_hca5wchca5wchca5.png](/static/img/ed7cce019c613c534439baa0551c118d.Gemini_Generated_Image_hca5wchca5wchca5.webp)

这篇是黑群晖安装流程的转载整理，适合在开装之前先过一遍关键步骤。虚拟机、引导、DSM 安装这些环节最好提前看清楚，免得装到一半才补资料。



文章来源：[安装Black群晖DSM7.2系统安装教程（在Vmware虚拟机中、实体机均可）](https://zhuanlan.zhihu.com/p/1986368295352427976)

# 准备工作

在开始安装之前，你需要准备：

• DSM 7.2 引导镜像（黑群晖专用引导）

• VMware Workstation或一台实体机

• 硬盘空间：建议至少 20GB 起步

• 网络环境：保证能访问到路由器，方便分配IP

• U盘，建议8G或以上（物理机使用，虚拟机不需要）

# 下载DSM7.2镜像文件

https://github.com/RROrg/rr/releases

下载rr-25.9.7.img.zip文件，到本地电脑上。

其中有三个文件 rr-25.9.7.img.zip和 rr-25.9.7.vhd.zip 和 rr-25.9.7.ova.zip 

## 三个文件有什么作用

1.rr-25.9.7.img.zip

作用：这是一个原始镜像文件（img），通常用于制作引导盘。

使用：解压后得到 .img 文件，用 Rufus 或 balenaEtcher 写入到 U盘，插入实体机，设置 BIOS 从U盘启动，即可进入 RR 引导界面。

2.rr-25.9.7.vhd.zip

作用：这是虚拟硬盘文件（VHD），微软 Hyper-V 等虚拟化平台能直接识别。

使用：在 Hyper-V 中新建虚拟机时，直接挂载这个 VHD 文件作为启动盘。

3.rr-25.9.7.ova.zip

这是虚拟机模板文件（OVA），包含虚拟机配置和磁盘镜像。

使用：在 VMware Workstation/ESXi 或 VirtualBox 中，直接导入 OVA 模板即可创建虚拟机。



# VMware安装步骤
DSM导入虚拟机（VMware示例）
1.导入文件
打开VMware虚拟机，选择 文件 → 打开

选择rr.ova

导入成功

2.打开虚拟机

3.用浏览器访问
在浏览器访问IP+7681

4.设置DSM
如图选择，Settings menu，再点击ok

如图选择choose a language，再点击ok

如图选择zh_CN中文，再点击ok

如图，选择时区，再点击ok

如图，选择Asia/Shanghai

再点击取消

选择型号

选择型号，DS918+

选择版本

pat版本

点击确认

5.安装Dsm
点击安装

如图，选择下载pat

下载包，再点击浏览，选择刚才下载的文件DSM_DS918+_86009.pat

确认删除数据

正在安装DSM

系统可能会重启。

6.欢迎界面

填写设备名称等信息。

更新选择，选择手动安装

跳过

提交

安装完成

这样就在虚拟机中安装成功，实体机安装选项类似，只是介质变成了u盘启动。

这个ova文件中只配置了32G的硬盘，你可以自己在虚拟机中添加硬盘。

# 实体机安装步骤

实体机安装要点

• 准备U盘作为引导盘

• BIOS中设置U盘优先启动

• 其他步骤与虚拟机类似

下载Rufus写入镜像

Rufus（物理机使用）：U盘镜像写入程序

下载地址：https://rufus.ie/zh/


把写好镜像的 U 盘插入实体机，重启电脑，按主板快捷键（一般是 F2、F11、Del，开机时屏幕会提示）进入 BIOS，把启动项改成 U 盘优先，保存退出

1. 开机后和虚拟机步骤一致：选择「configure loader」→中文→型号 DS918+→版本 7.2→PAT 版本 7.2.2-72806-0→编译引导→启动
2. 记录下屏幕显示的 IP + 端口号，用浏览器访问，后续安装步骤和虚拟机完全相同（手动上传 PAT 文件、设置账户密码、创建存储池等）
3. 安装完成后，拔掉 U 盘，下次开机就会直接从硬盘启动 DSM 系统
# 总结

以上就是Black群晖 DSM7.X 系统的完整安装流程，虚拟机试水、实体机长期用都覆盖到了，实测两种方案都能一次成功！ DSM 系统简单易用、稳定性强，不管是存资料、搭影音库还是做文件同步，都能满足需求。

【转载】黑群晖安装教程

![](/static/img/02c9d7a1dfd690c2b039b2d781a153e2.Gemini_Generated_Image_jjti7njjti7njjti.webp)

Windows 重装后最烦的就是重复点安装包。于是用 PowerShell 和 Winget 写一份自动化脚本，把常用软件、环境初始化和批量装机流程尽量交给命令完成。



# （下载地址在文末）

## 1. 背景与需求

在 Windows 环境下进行批量装机或重装系统后，软件部署通常面临以下痛点：

* **Winget 的局限性**：官方源虽然方便，但部分软件版本滞后，或缺少特定版本（如去广告版、绿色版）。
* **本地安装的繁琐**：传统的批处理安装（`.bat`）难以处理静默参数不统一、进程卡死等异常情况。
* **重复安装问题**：脚本若重复运行，可能会覆盖已配置好的软件。

基于此，编写了一个 PowerShell 脚本 (`AutoInstall.ps1`)，采用 **“Winget 在线 + Local 离线”** 的混合部署策略，并加入了进程监控和注册表查重机制。

## 2. 核心技术实现

### 2.1 混合数据源架构

脚本将部署流程分为两个阶段，逻辑解耦：

1. **在线阶段**：解析 `my_apps.txt` 配置文件，调用系统内置 `winget` 部署常用软件（Chrome, VSCode 等）。支持通过标签 `# [SOURCE: msstore]` 动态切换下载源。
2. **离线阶段**：遍历 `Local_Apps` 目录，根据文件后缀（`.exe`/`.msi`/文件夹）自动匹配安装策略。

### 2.2 基于注册表的“幂等性”检测 (查重)

为了防止重复安装，脚本在本地部署阶段引入了预检查机制。

* **原理**：通过读取 `HKLM` 和 `HKCU` 下的 `Uninstall` 注册表项，构建已安装软件名称列表。
* **匹配**：将待安装文件名与已安装列表进行模糊匹配（Regex）。

```powershell
# 获取系统已安装软件列表
function Get-InstalledAppNames {
    $paths = @(
        "HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\*",
        "HKLM:\SOFTWARE\WOW6432Node\Microsoft\Windows\CurrentVersion\Uninstall\*",
        "HKCU:\Software\Microsoft\Windows\CurrentVersion\Uninstall\*"
    )
    $names = @()
    foreach ($path in $paths) {
        Get-ItemProperty $path -ErrorAction SilentlyContinue | ForEach-Object {
            if ($_.DisplayName) { $names += $_.DisplayName }
        }
    }
    return $names
}

```

### 2.3 进程熔断机制 (Timeout)

在使用 `winget` 或调用外部 `exe` 时，可能会出现网络挂起或安装程序卡死的情况。
脚本放弃了简单的 `Wait-Process`，改用循环轮询的方式监控进程运行时间。一旦超过阈值（默认 10 分钟），强制终止进程。

```powershell
# 启动进程并获取对象
$proc = Start-Process -FilePath $exe -ArgumentList $args -PassThru -NoNewWindow

$startTime = Get-Date
while (-not $proc.HasExited) {
    Start-Sleep -Seconds 2
    # 计算运行时长
    if (((Get-Date)-$startTime).TotalMinutes -ge $TimeLimitMinutes) {
        Stop-Process -Id $proc.Id -Force -ErrorAction SilentlyContinue
        Write-Host " [!] 任务超时，强制熔断。" -ForegroundColor Red
        break 
    }
}

```

### 2.4 动态说明映射

本地文件通常只有英文文件名（如 `SoftCnKiller.exe`）。脚本内置了一个哈希表（HashTable）字典，在运行时动态匹配文件名并输出中文说明，提升日志可读性。

```powershell
$AppDict = @{
    "finalshell" = "SSH连接/服务器管理"
    "softcnkiller" = "流氓软件清理工具"
    "wiztree"    = "磁盘空间分析"
    # ...
}

```

## 3. 脚本目录规范

为了保证脚本的可移植性（Portable），采用相对路径结构：

```text
Deploy_Tool_V33/
│
├── 一键启动.bat          # 引导层：负责提权和绕过执行策略
├── AutoInstall.ps1       # 逻辑层：PowerShell 核心代码
├── my_apps.txt           # 配置层：Winget 软件清单
│
└── Local_Apps/           # 数据层：存放本地安装包
    ├── setup_v1.0.exe
    └── PortableTool/     # 支持直接复制绿色软件目录

```

## 4. 异常处理策略

脚本针对几种常见的安装失败场景做了处理：

1. **Winget 找不到包**：捕获 ExitCode，若非 0 或 3010（重启），则输出错误代码供排查。
2. **静默安装失败**：本地 EXE 默认尝试 `/S` 或 `/silent` 参数。如果进程快速退出且未成功（依据返回码），脚本会提示用户可能需要手动介入，但不会中断整个流程。
3. **UI 对齐**：针对中英文混合输出导致的控制台对齐问题，编写了 `Show-Header` 函数，基于字符字节宽度计算 Padding，确保日志输出整洁。

## 5. 使用说明

1. **配置**：修改 `my_apps.txt` 添加需要的 Winget ID；将离线包放入 `Local_Apps`。
2. **运行**：直接运行 `一键启动.bat`。
3. **交互**：脚本启动后会要求输入“部署路径”（针对绿色软件）和“超时时间”，随后自动执行。

---

**下载地址**：
[整合包下载地址](https://www.123865.com/s/3OzeVv-wsWQv?pwd=6666#)

基于 PowerShell 与 Winget 的 Windows 自动化部署脚本