本地预览个人主页（远程 headless Ubuntu 服务器）

面向环境：远程 SSH 登录的 Ubuntu 22.04 服务器（无图形界面），本机已检测到 Ruby 3.0.2 + gem 3.3.5，但没有 bundler / jekyll / docker，也没有免密 sudo。本文给出的命令均基于该实测环境，可直接复制执行。

TL;DR（最快路径）

# 0) 进入仓库
cd ~/mn_research_code/moonoutcloudback.github.io

# 1) 一次性安装系统编译依赖（需要 sudo 密码）
sudo apt update && sudo apt install -y ruby-dev libxml2-dev libxslt1-dev

# 2) 让 gem 装到你的家目录（之后所有 gem 命令都不再需要 sudo）
echo 'export GEM_HOME="$HOME/.gem"'     >> ~/.bashrc
echo 'export PATH="$GEM_HOME/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
gem install bundler

# 3) 安装本仓库的依赖（首次较慢，约 3–8 分钟）
bundle config set --local path 'vendor/bundle'
bundle install

# 4) 启动本地预览服务
bundle exec jekyll serve

# 5) 在【你自己的笔记本】上开一个新终端做 SSH 端口转发：
ssh -L 4000:localhost:4000 mn@166.111.72.154
#    然后用笔记本浏览器打开  http://localhost:4000

下面逐条解释。

1. 这台电脑上需要装什么

本站点是 Jekyll 站点（GitHub Pages 原生支持的静态站点生成器）。本地预览 = 在服务器上跑一个 Jekyll 开发服务器，再通过 SSH 端口转发用你笔记本的浏览器访问。

实测本机现状：

组件	状态
Ruby 3.0.2 / gem 3.3.5	✅ 已有（系统自带）
build-essential / gcc / make	✅ 已有
zlib1g-dev	✅ 已有
ruby-dev	❌ 需安装（编译原生扩展要用到 `ruby.h`）
libxml2-dev / libxslt1-dev	❌ 需安装（nokogiri 解析库要用）
bundler / jekyll	❌ 没有，下面用 gem 装（无需 sudo）
docker	❌ 没有（可选，见「方案 B」）

1.1 一次性系统依赖（需要 sudo 密码）

sudo apt update
sudo apt install -y ruby-dev libxml2-dev libxslt1-dev

这一步是唯一需要 sudo 的地方。因为系统没有免密 sudo，请在终端里直接执行（在 Claude Code 里可以用 ! sudo apt install -y ruby-dev libxml2-dev libxslt1-dev 让它在当前会话里运行并接收你输入的密码）。

1.2 用户态 Ruby 工具链（无需 sudo）

把 gem 的安装目录指向你的家目录，避免写系统目录的权限问题：

echo 'export GEM_HOME="$HOME/.gem"'     >> ~/.bashrc
echo 'export PATH="$GEM_HOME/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

gem install bundler      # 装好后 bundler 命令可用

2. 安装本仓库依赖 & 启动预览

cd ~/mn_research_code/moonoutcloudback.github.io

# 让 bundler 把依赖装进仓库内的 vendor/bundle（已在 .gitignore 中，不会污染 git）
bundle config set --local path 'vendor/bundle'
bundle install            # 首次会编译原生扩展，耐心等几分钟

# 启动开发服务器（默认监听 http://127.0.0.1:4000）
bundle exec jekyll serve

bundle exec jekyll serve 会持续运行并在文件改动时自动重建。按 Ctrl+C 停止。
想开启浏览器自动刷新：bundle exec jekyll serve --livereload。

只想验证能否构建（不启服务）

bundle exec jekyll build       # 产物输出到 _site/，成功后即退出

3. 在 headless 服务器上怎么看页面？—— SSH 端口转发

服务器没有浏览器，Jekyll 又只监听服务器自己的 localhost:4000。解决办法：在你本地的笔记本上做 SSH 端口转发，把服务器的 4000 端口映射到你笔记本的 4000 端口。

在笔记本（不是服务器）开一个终端：

ssh -L 4000:localhost:4000 mn@<服务器地址>

保持这个 SSH 连接着，然后用笔记本浏览器打开：

http://localhost:4000

即可看到你的主页。改完 Markdown/YAML 后，Jekyll 会自动重建，刷新浏览器即可。

安全提示：用 ssh -L … localhost:4000 即可，不需要给 jekyll 加 --host 0.0.0.0（那样会把站点暴露给整台服务器的网络）。

4. 方案 B：用 Docker（可选，如果你装了 Docker）

本仓库自带 Dockerfile / docker-compose.yaml / _config_docker.yml。如果你更想用容器：

# 安装 docker（需要 sudo）
sudo apt install -y docker.io
sudo usermod -aG docker $USER && newgrp docker   # 免 sudo 跑 docker

cd ~/mn_research_code/moonoutcloudback.github.io
docker compose up        # 同样在 localhost:4000 起服务

然后照旧用第 3 节的 SSH 端口转发查看。Docker 的好处是不污染系统 Ruby；缺点是要先装 docker、镜像首次拉取较慢。

5. 常见问题

bundle install 报缺 ruby.h / mkmf → 没装 ruby-dev，回到 1.1。
bundle install 报 nokogiri 编译失败 → 没装 libxml2-dev libxslt1-dev，回到 1.1。
jekyll: command not found → 没用 bundle exec 前缀，或 GEM_HOME/bin 没进 PATH（检查 echo $PATH）。
页面 404 或样式丢失 → 确认用 http://localhost:4000 访问，且 _config.yml 的 url/baseurl 没被改坏。本地预览时 baseurl 必须为空（""）。
端口 4000 被占用 → 换一个：bundle exec jekyll serve --port 4001，SSH 转发也改成 4001。
改了 _config.yml 不生效 → 配置文件改动需要重启 jekyll 服务（重启 bundle exec jekyll serve）。

6. 推送即自动部署

本地预览只是开发用。把改动 git push 到 GitHub 后，GitHub Pages 会自动构建并发布到 https://moonout.link（由根目录 CNAME 决定）。所以流程是：本地预览 → git commit → git push → 在线自动更新。

git add -A
git commit -m "customize academic homepage"
git push

Ni Mu