前言

前两篇记录了迷你主机的选购和 Debian 系统的安装。系统装好后，接下来面临的问题是：如何快速配置完整的开发环境？之前在 WSL 下每次重装都要手动装 Go、Java、Node.js，还要配各种镜像源，流程繁琐且容易遗漏。这次决定把所有配置脚本化，形成一套可重复执行的 setup 工具，一键完成环境部署。本文记录整个配置体系的设计和实现过程。

一、设计思路

1.1 核心原则

配置脚本的设计遵循几条基本原则：

• 幂等性 — 每个脚本可反复执行，已安装的跳过、配置相同的跳过，不会产生覆盖或冗余
• 缓存统一 — 包管理器缓存（apt、npm、pip、Go、Maven）统一放在 cache/ 目录下，重装系统不丢失
• 安装包归档 — 下载的安装包存放在 packages/ 目录，按软件分类，支持离线部署
• 国内镜像加速 — 所有包管理器统一配置清华/阿里云镜像，解决国内下载慢的问题
• 交互/静默双模式 — 支持交互式菜单选择执行，也支持 --silent 参数用于自动化部署

1.2 目录结构

text
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
workspace/
├── setup/
│   ├── common.sh          # 公共函数（日志、路径、交互工具）
│   ├── init.sh            # 入口脚本（菜单/静默模式）
│   ├── modules/           # 模块脚本，按编号顺序执行
│   │   ├── 00-ssh.sh
│   │   ├── 01-apt-sources.sh
│   │   └── ...
│   ├── keys/              # SSH 公钥目录
│   └── README.md          # 完整文档
├── cache/                 # 运行时缓存
│   ├── go/
│   ├── maven/
│   └── npm/
└── packages/              # 安装包离线归档
    ├── golang/
    ├── miniconda/
    ├── texlive/
    └── zellij/

二、使用方式

2.1 快速开始

bash
1
2
3
4
5
6
7
8
9
# 克隆仓库
git clone https://github.com/DoraTiger/homelab-setup.git
cd homelab-setup

# 交互式菜单
bash init.sh

# 静默执行全部
bash init.sh --silent

2.2 交互式菜单

bash
1
bash init.sh

启动后显示路径信息和模块列表，输入编号选择执行：

text
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Homelab Debian 环境配置工具
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  项目路径:   /home/tiger/workspace
  缓存目录:   /home/tiger/workspace/cache
  安装包:     /home/tiger/workspace/packages
  密钥目录:   /home/tiger/workspace/setup/keys
  代理状态:   未配置
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  可用模块:
  ────────────────────────────────────────────────
    [ 0] 00-ssh.sh            SSH 密钥生成与 authorized_keys 配置
    [ 1] 01-apt-sources.sh    APT 软件源配置
    [ 2] 02-git-config.sh     Git 全局配置
    ...
    [13] 13-zellij.sh         Zellij 终端复用器安装
  ────────────────────────────────────────────────
    [a]  全部执行     [p]  配置代理     [q]  退出

2.3 静默模式

bash
1
2
3
4
5
6
7
8
# 执行全部模块
bash init.sh --silent

# 执行指定模块（按编号）
bash init.sh --silent 1 3

# 使用代理
bash init.sh --silent --proxy socks5://127.0.0.1:7890

2.3 代理配置

网络受限时可通过代理确保下载稳定。支持 http://、https://、socks5:// 格式。模块中的 wget/curl 下载会自动走代理。

三、模块详解

3.1 基础设施

编号	模块	功能	升级方式
00	ssh	生成密钥 + 合并远程公钥 + 自动设权限	—
01	apt-sources	清华镜像源（自动 DEB822/传统）+ 基础工具 + apt upgrade	apt upgrade
02	git-config	交互式配置用户名/邮箱/默认分支/常用别名	—

3.2 容器与运行时

编号	模块	功能	升级方式
03	docker	Docker CE + Compose + Buildx + 镜像加速 + daemon 配置	apt --only-upgrade
04	miniconda	Miniconda3 + conda/pip 清华镜像 + Shell 初始化	conda update --all
05	golang	Go 多版本管理 + GOPROXY 清华镜像 + symlink 切换	自动下载最新版
06	java	SDKMAN + Java 21 (Temurin) + Maven + 阿里云镜像	sdk selfupdate + sdk upgrade
07	nodejs	fnm + Node.js LTS + npmmirror + npm 全局目录	fnm upgrade + npm install -g npm@latest

3.3 语言工具链

编号	模块	功能	升级方式
08	perl-cpan	CPAN 清华镜像 + local::lib 用户级模块管理	—
09	r-lang	CRAN 清华镜像 + r-base-dev	apt upgrade
10	rust	rustup + Rust stable + crates.io 清华镜像	rustup update stable
11	texlive	TeX Live 全量安装 + CTAN 清华镜像 + tlmgr	tlmgr update --all

3.4 桌面与工具

编号	模块	功能	升级方式
12	xrdp	XRDP + XFCE4 + polkit WiFi 修复	apt upgrade
13	zellij	预编译二进制 + dracula 主题 + 快捷别名	重新下载覆盖

四、技术细节

4.1 交互工具

common.sh 提供统一的交互函数，所有模块共享：

bash
1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 单选菜单
type=$(prompt_choice "选择密钥类型:" "ed25519" "ed25519" "rsa-4096" "ecdsa")

# 是/否确认
if prompt_yesno "是否配置镜像源?" "y"; then ... fi

# 文本输入
name=$(prompt_input "用户名:" "$(whoami)")

# 密码输入（隐藏回显）
pass=$(prompt_secret "请输入密码")

# 表格展示
prompt_table "文件名|类型|说明" "id_ed25519.pub|ed25519|本机密钥"

静默模式下所有函数自动使用默认值，不阻塞等待输入。

4.2 幂等性设计

每个模块脚本遵循统一的幂等模式：

bash
1
2
3
4
5
6
7
8
9
10
11
# 检测是否已安装
if [ -f "$INSTALL_DIR/bin/xxx" ]; then
    log_success "xxx 已安装"

    # 检测是否需要升级
    log_info "检查升级..."
    xxx upgrade 2>/dev/null || true
else
    # 执行安装
    log_info "安装 xxx..."
fi

4.3 环境变量管理

所有环境变量通过 .bashrc.d/ 目录管理，每个模块一个文件：

text
1
2
3
4
5
6
7
8
9
~/.bashrc.d/
├── conda.sh       # Miniconda
├── go.sh          # Go
├── nodejs.sh      # fnm + Node.js
├── perl.sh        # Perl local::lib
├── rust.sh        # Rust
├── sdkman.sh      # SDKMAN
├── texlive.sh     # TeX Live
└── zellij.sh      # Zellij 别名

.bashrc 中通过统一的加载器遍历执行：

bash
1
2
3
4
5
6
# Load environment snippets
if [ -d "$HOME/.bashrc.d" ]; then
    for f in "$HOME"/.bashrc.d/*.sh; do
        [ -f "$f" ] && . "$f"
    done
fi

4.4 镜像源汇总

工具	镜像源
APT	https://mirrors.tuna.tsinghua.edu.cn/debian
Docker	https://mirrors.tuna.tsinghua.edu.cn/docker-ce
conda	https://mirrors.tuna.tsinghua.edu.cn/anaconda
pip	https://pypi.tuna.tsinghua.edu.cn
Go	https://goproxy.cn
Maven	https://maven.aliyun.com
npm	https://registry.npmmirror.com
crates.io	https://mirrors.tuna.tsinghua.edu.cn/crates.io-index
CRAN	https://mirrors.tuna.tsinghua.edu.cn/CRAN
CTAN	https://mirrors.tuna.tsinghua.edu.cn/CTAN
rustup	https://mirrors.tuna.tsinghua.edu.cn/rustup

五、总结

整套 setup 工具覆盖了从 SSH 密钥到桌面环境的全链路配置，14 个模块脚本按依赖优先级排序，支持交互式选择和静默批量执行。所有工具统一安装到 ~/.local/opt/，环境变量通过 .bashrc.d/ 管理，国内镜像源统一配置，重复执行安全无副作用。后续新增模块只需在 modules/ 下添加脚本，菜单自动识别。

本文涉及的所有脚本已开源在 homelab-setup 仓库中，欢迎 clone 使用和反馈。

参考

• homelab-setup GitHub
• 清华大学开源软件镜像站
• Docker CE 清华镜像
• SDKMAN 安装文档
• fnm GitHub
• TeX Live 清华镜像
• TeX Live 安装指南