运维 on 寻 Mi 处

再也不用 scp 传文件了，push 一下博客就上线

Thu, 12 Dec 2024 04:58:00 +0800

以前写博客的流程是这样的。

本地写完，hugo 构建，然后用 FileZilla 把 public 目录拖到服务器上。拖的时候还不能直接覆盖，得先删掉旧的，再传新的，不然会残留一堆已经删掉的文章。

有几次传了一半网断了，网站变成了半新半旧的状态，首页能打开，点进去文章 404。还有一次拖错了目录，把 public 传到了上一级，整站挂了半小时。

后来我改用 rsync，好一些，但还是要手动敲命令。再后来加了 --delete，又差点把服务器上别的目录删了。

这种手动流程，出问题是迟早的。

换个思路

其实我要的事情很简单。本地 git push 之后，服务器上自动更新网站。

Git 本身就能做这件事。服务器上建一个裸仓库，配置一个 post-receive 钩子，每次收到 push 就执行一段脚本。脚本里做的事情就是把代码检出到工作目录，然后构建。

这个方案的好处是不依赖任何外部服务。不用 GitHub Actions，不用 Jenkins，不用装一堆东西。一台有 git 的机器就能跑。

服务器上建裸仓库

登录服务器：

`1`	`ssh blog`

建目录：

1
2

sudo mkdir -p /srv/git/blog.git
sudo chown -R git:git /srv/git

这里我专门建了个 git 用户，不用 root，也不用我自己的账号。原因后面说。

初始化裸仓库：

`1`	`sudo -u git git init --bare /srv/git/blog.git`

--bare 的意思是只有 git 数据，没有工作区。你不能在这个目录里直接看到文件，它是纯粹用来接收 push 的。

建一个工作目录

网站的实际文件要放在另一个地方，比如 /srv/www/blog：

1
2

sudo mkdir -p /srv/www/blog
sudo chown -R git:git /srv/www/blog

注意属主是 git，因为钩子是以 git 用户的身份跑的。如果属主是 root，钩子里的写操作会失败。

写钩子

钩子的位置是固定的：

`1`	`sudo -u git nano /srv/git/blog.git/hooks/post-receive`

内容：

#!/bin/bash
set -euo pipefail

WORK=/srv/www/blog
GIT_DIR=/srv/git/blog.git

while read oldrev newrev refname; do
  if [ "$refname" = "refs/heads/main" ]; then
    echo "==> 部署 main 分支到 $WORK"
    git --work-tree="$WORK" --git-dir="$GIT_DIR" checkout -f main
    cd "$WORK"
    hugo --minify --gc
    echo "==> 部署完成"
  fi
done

给执行权限：

`1`	`sudo chmod +x /srv/git/blog.git/hooks/post-receive`

while read oldrev newrev refname 这一段是标准写法。push 的时候 git 会把每个被更新的引用通过标准输入传给你，格式是三列。只处理 main 分支，别的分支推上来不触发部署。

checkout -f 里的 -f 很重要。它会强制覆盖工作区里的文件，不管有没有本地修改。不加这个，第二次部署就会因为文件冲突失败。

hugo --minify --gc 是构建。--minify 压缩 html、css、js，--gc 清理掉不再引用的缓存资源。这两个参数在 Hugo 0.115 之后都还在用。

本地配置远程

`1`	`git remote add deploy ssh://git@blog.mibase.top/srv/git/blog.git`

或者用 scp 风格的写法：

`1`	`git remote add deploy git@blog.mibase.top:/srv/git/blog.git`

两种都行，前者更明确一点。

然后：

`1`	`git push deploy main`

第一次推的时候，终端里应该能看到钩子输出的那几行。

权限这块是最大的坑

我一开始用的是自己的账号，没建 git 用户。结果钩子跑起来各种 Permission denied。

原因是 SSH 登录的用户和钩子执行脚本的用户必须是同一个，而且这个用户要对工作目录有写权限，对 nginx 的目录也要有读权限。

后来我理清了：

git 用户拥有裸仓库和工作目录。nginx 以 www-data 身份跑，需要有读权限。所以我把工作目录的组设成 www-data，权限给到 750：

1
2
3

sudo chown -R git:www-data /srv/www/blog
sudo chmod -R 750 /srv/www/blog
sudo usermod -aG www-data git

这样 git 用户能写，www-data 能读，别人进不来。

还有一个 SELinux 的问题。如果你用的是 CentOS 或者 RHEL，默认的 SELinux 策略会阻止 nginx 读 /srv 下面的文件。得打标签：

1
2

sudo semanage fcontext -a -t httpd_sys_content_t "/srv/www/blog(/.*)?"
sudo restorecon -Rv /srv/www/blog

Debian 和 Ubuntu 没这个烦恼。

只给 git 用户最小权限

用 git 用户有个额外的好处，就是可以限制它能做的事。

编辑 /etc/passwd，把这个用户的 shell 从 /bin/bash 改成 /usr/bin/git-shell：

`1`	`git:x:998:998::/srv/git:/usr/bin/git-shell`

git-shell 是一个受限的 shell，只允许 git 相关的命令，别的命令一律拒绝。这样就算有人拿到了这个账号的私钥，也登不进交互式的 shell，只能在 git 协议里操作。

这个设置很值得做。我之前的机器被人扫过 SSH 密码，虽然没成功，但那之后我就把能限制的地方都限制了。

nginx 那边

配置里 root 指到工作目录的 public：

server {
    listen 443 ssl http2;
    server_name blog.mibase.top;

    root /srv/www/blog/public;
    index index.html;

    location / {
        try_files $uri $uri/ =404;
    }
}

Hugo 构建完之后，静态文件在 public 子目录里，所以 root 要指到那一层。

增量构建的问题

如果博客文章多了，每次全量构建会比较慢。Hugo 支持增量：

`1`	`hugo --minify --gc --buildDrafts=false`

不过增量构建有它自己的问题，改了模板或者配置之后，有时候不会重新生成所有页面，导致部分页面还是旧的。我的经验是，日常发文用增量，改主题或者配置的时候手动跑一次全量。

Hugo 0.123 之后引入了一个 --renderToMemory 的选项，构建更快，但对大站内存要求高。我这种几十篇文章的站感觉不出差别。

多个站点的做法

后来我又加了一个笔记站，用的是同一套方案。

裸仓库和钩子都是独立的，互不干扰。唯一要改的是钩子里的路径和构建命令。

我把钩子的公共部分抽成了一个脚本，放在 /srv/git/deploy.sh，两个钩子都去调它，传不同的参数：

#!/bin/bash
set -euo pipefail
WORK=$1
BRANCH=${2:-main}

while read oldrev newrev refname; do
  if [ "$refname" = "refs/heads/$BRANCH" ]; then
    git --work-tree="$WORK" --git-dir="$GIT_DIR" checkout -f "$BRANCH"
    cd "$WORK"
    hugo --minify --gc
  fi
done

GIT_DIR 是 git 在执行钩子时自动设的环境变量，不用自己传。

出问题怎么回滚

这个方案有个小遗憾，它没有版本回退的功能。工作目录里永远是 main 分支的最新内容。

要回滚的话，有两个办法。

一个是在本地 revert 一个 commit，再 push 一次。这个最干净，历史是线性的。

另一个是直接在服务器上操作：

cd /srv/www/blog
git log --oneline -5
git checkout <COMMIT_ID> -- .
hugo --minify --gc

但这样工作目录会和裸仓库脱节，下次 push 的时候 checkout -f 会把你的手动修改全冲掉。所以我一般用第一种。

什么时候该换个方案

这套方案适合个人博客，不适合团队协作。

如果有多个人一起维护，你可能会想要在 push 之后跑测试、跑 lint、生成预览链接。这些用 GitHub Actions 或者 Gitea 的 CI 会方便很多。

还有一种是构建时间很长的站。我见过有人 Hugo 站有几千篇文章，全量构建要三分钟。这种情况下每次 push 都要等三分钟，体验不好，得考虑缓存或者增量。

我现在的站只有几十篇，构建三秒，用这套方案正合适。

现在的感受

最大的变化是心理上的。

以前想写点东西，会先想到"还得传文件"，这个念头本身就会让人拖延。现在打开编辑器就写，写完 push，完事。中间那一步消失了，写东西的阻力小了很多。

这种小工具的收益，往往不在技术本身，而在它把你从一件烦人的事情里解放出来。省下的那几分钟不重要，重要的是你不再因为烦而逃避。

用了两年 Docker Compose，我把这些套路固定下来了

Tue, 26 Mar 2024 06:32:00 +0800

刚开始用 Docker 那阵子，我特别喜欢在命令行里敲 docker run。参数一行能拉出去两百多个字符，-v、-p、-e 混在一起，看着挺有成就感。

直到有一次我为了调一个环境变量，把容器删了重建，结果忘了当初挂载的路径是哪个。数据卷还在，但容器起不来了，日志里全是找不到配置文件的报错。我在 docker inspect 的输出里翻了十几分钟，才从一个早已忘记的临时目录里把东西找回来。

那次之后我就老老实实用 Compose 了。现在服务器上所有的服务，都是一个个 compose.yaml 管着。

为什么是 Compose 而不是别的

有人会说，你都上 Docker 了，干嘛不上 Kubernetes。

我的答案很朴素，我就一台 2 核 4G 的机器，跑着七八个容器。K8s 的控制面自己就要吃掉一两个 G，剩下的空间还不够我塞服务。而且我一个人维护，出问题的时候需要的是能快速看懂的东西，不是一整套抽象。

Compose 的好处是，所有配置都在一个文件里，看得见摸得着。改完 docker compose up -d，它自己算差异，只重建变化的部分。要回滚就把文件换回去再 up 一次。

还有个被低估的点，就是文件本身就是文档。半年后我忘了某个服务是怎么配的，打开文件一看全明白了。

目录怎么摆

我现在的习惯是，所有服务放在 /srv 下面，一个服务一个目录：

/srv
├── blog
│   ├── compose.yaml
│   └── data
├── db
│   ├── compose.yaml
│   ├── conf
│   └── data
├── proxy
│   ├── compose.yaml
│   ├── conf.d
│   └── certs
└── monitor
    ├── compose.yaml
    └── data

数据统一放在服务目录下的 data 子目录，然后挂载进去。这样备份的时候，把 /srv 整个打包就够了，不用去 /var/lib/docker 里翻那些名字是哈希的目录。

这一点很关键。Docker 的具名卷虽然方便，但它在文件系统里藏在 /var/lib/docker/volumes/ 下面，备份脚本写起来很难看。用 bind mount 直接映射到自己的目录，什么都清楚。

一个完整的例子

拿博客举例。我的博客是 Hugo 生成的静态文件，用一个 nginx 容器托管：

services:
  blog:
    image: nginx:1.25-alpine
    container_name: blog
    restart: unless-stopped
    ports:
      - "127.0.0.1:8080:80"
    volumes:
      - ./public:/usr/share/nginx/html:ro
      - ./conf.d:/etc/nginx/conf.d:ro
    healthcheck:
      test: ["CMD", "wget", "-q", "--spider", "http://127.0.0.1/"]
      interval: 30s
      timeout: 5s
      retries: 3
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

几个地方值得说。

ports 我只绑了 127.0.0.1，不写 0.0.0.0。意思是这个端口只能从本机访问，外面进不来。真正对外的入口交给 nginx 反向代理，这样容器端口就不会直接暴露在公网上。这一点在我被扫过几次之后变得特别重要。

restart: unless-stopped 而不是 always。区别在于，我手动 docker compose stop 之后，unless-stopped 的容器重启机器也不会自己起来，always 会。调试的时候这个区别能省不少事。

logging 那段一定要加。Docker 默认的 json-file 日志没有大小限制，一个话多的服务跑上几个月，能把磁盘写满。我第一次被磁盘告警吵醒就是因为这个，日志文件堆到了 20 多个 G。

healthcheck 是给后面的 depends_on 用的，下面会讲。

数据库和依赖顺序

数据库的 compose 我一般这么写：

services:
  mariadb:
    image: mariadb:11.2
    container_name: mariadb
    restart: unless-stopped
    environment:
      MARIADB_ROOT_PASSWORD_FILE: /run/secrets/db_root
      MARIADB_DATABASE: app
      MARIADB_USER: app
      MARIADB_PASSWORD_FILE: /run/secrets/db_app
      TZ: Asia/Shanghai
    volumes:
      - ./data:/var/lib/mysql
      - ./conf/my.cnf:/etc/mysql/conf.d/my.cnf:ro
    ports:
      - "127.0.0.1:3306:3306"
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      interval: 10s
      timeout: 5s
      retries: 10
      start_period: 30s

secrets:
  db_root:
    file: ./secrets/db_root.txt
  db_app:
    file: ./secrets/db_app.txt

密码用 secrets 而不是直接写 environment。这样 docker inspect 出来的环境变量里看不到明文，compose.yaml 也可以放心提交到私有仓库。文件权限设成 600 就行。

start_period 这个参数新手容易忽略。它是给容器一个"还在启动中，别急着判定失败"的宽限期。MariaDB 第一次初始化数据目录要花几十秒，不设这个，健康检查会一直失败，把容器标记成 unhealthy。

healthcheck.sh 是 MariaDB 官方镜像自带的脚本，比自己拼 mysqladmin ping 可靠，因为它会真的等到 InnoDB 初始化完。

应用那边要等数据库好了再起，就这么写：

  app:
    image: myapp:latest
    depends_on:
      mariadb:
        condition: service_healthy

注意是 service_healthy，不是默认的 service_started。默认那个只保证容器进程起来了，不保证里面服务能连。我第一次用默认值的时候，应用每次重启都要重试好几次才连上数据库，日志里一堆 connection refused。

网络怎么连

Compose 默认会给项目建一个 bridge 网络，同一个文件里的服务互相用服务名就能访问。这个挺好用，但跨文件就不行了。

我有两个选择。要么把相关服务塞进同一个 compose 文件，要么建一个外部网络让它们共享。

我选了后者，因为数据库和博客的更新节奏不一样，混在一个文件里，改博客的配置会把数据库也带着重建一次，太危险。

建网络：

`1`	`docker network create --driver bridge shared`

然后每个文件里都声明：

1
2
3

networks:
  shared:
    external: true

服务上再加一句：

1
2

    networks:
      - shared

这样博客容器里直接 ping mariadb 就能通。

不过这里有个坑，container_name 和自定义网络里的服务名是两套东西。用 container_name 的时候，容器在网络里的别名是那个名字，不是 services 下的键。我一开始没注意，配置里写服务名连不上，改成 container_name 才对上。

我的建议是干脆别用 container_name，让 Compose 自己按 项目名-服务名-序号 生成。虽然名字长一点，但不会和别的项目冲突，扩容的时候也不会撞名。

反代那一层

nginx 做反向代理的容器，配置文件单独放：

server {
    listen 80;
    server_name blog.mibase.top;

    location / {
        proxy_pass http://blog:80;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

proxy_pass 里写的是容器名，因为它在同一个 shared 网络里，Docker 的内置 DNS 会解析。

X-Forwarded-For 这几行别省。省了之后，nginx 的访问日志里全是反代容器的内网 IP，你想看真实访客来源就看不到了。Cloudflare 那边传过来的真实 IP 也会在这一层层里丢掉。

更新镜像的流程

我不用 watchtower 那种自动更新的东西。自动更新很爽，但它会在你睡觉的时候把一个能跑的服务换成一个跑不起来的版本。

我的流程是手动但固定：

cd /srv/db
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=50

拉完先看 ps，确认状态是 running 并且 healthy，再看日志有没有报错。有问题就 docker compose down 然后换回上一个 tag。

所以镜像 tag 我尽量不用 latest，写具体版本号。mariadb:11.2 比 mariadb:latest 可控太多了。

备份怎么配合

因为数据都在 /srv/*/data 下面，备份脚本写起来很直接：

#!/bin/bash
set -euo pipefail
ts=$(date +%F)
tar -czf /backup/srv-$ts.tar.gz -C / srv --exclude='*/cache/*'

不过数据库不能这么直接打包，热备份出来的文件可能是不一致的。数据库我单独用 mariadb-dump 导出：

`1`	`docker compose exec -T mariadb mariadb-dump --all-databases --single-transaction > /backup/db-$ts.sql`

--single-transaction 保证导出的是一个一致的时间点，不会因为导出过程中有人写入而错乱。

写在最后

Compose 这个工具本身不复杂，难的是把使用习惯固定下来。

我现在新加一个服务，基本就是复制一个已有的目录，改改镜像名和端口，十分钟能跑起来。出问题的时候也知道去哪儿看，日志在哪、数据在哪、配置在哪，都是固定的位置。

这套东西没什么高深的技术，但它让我在面对一台跑了两年、装着七八个服务的机器时，心里是有底的。这大概就是运维这件事最实际的价值。