部署笔记:在 2 核 2 GB 服务器上实现自动上线

文章目录CONTENTS ↓

这篇记录一个个人站点从本地运行到自动上线的过程。服务器配置是 2 核 CPU、2 GB 内存,应用包括静态站点、私人笔记前端,以及 Go API 和 SQLite。

项目为什么这样拆分、笔记功能如何设计,放在另一篇项目笔记:从博客、自学中心到私人笔记中。这里集中记录部署配置、执行命令和实际遇到的问题。

部署前的约定

这套应用运行两个容器:web 使用 Caddy 提供静态文件和反向代理,api 运行 Go 服务。SQLite 文件放在 API 挂载的持久化卷中,不需要单独的数据库容器。构建在 GitHub Actions 完成,服务器只运行产物。

浏览器 → HTTPS → web(Caddy)
├─ example.com → 导航页
├─ blog.example.com → 博客和自学中心
└─ note.app.example.com
├─ 静态页面 → React 构建产物
└─ 认证与数据请求 → api:8080 → SQLite 持久化卷

文章中的域名统一使用 example.com 及对应子域名,公网 IP、SSH 端口、邮箱和 GitHub 用户名也使用示例值。复现时需要换成自己的配置;example.com 不是供读者申请证书或部署的真实目标。

配置节选会明确标注,不是一份可以从头到尾直接执行的安装脚本。服务器原本已经安装 Docker 和 Compose,因此这里不展开安装过程。

Dockerfile:把构建环境和运行环境分开

Dockerfile 描述如何生成镜像。镜像是可以部署的程序包,容器则是镜像启动后的运行实例。

前端镜像使用多阶段构建。下面是结构节选,省略了实际文件中的站点名称、备案号等构建参数:

deploy/Dockerfile.web
FROM node:24-alpine AS build
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm ci --prefix apps/notes \
&& npm run build \
&& npm run build --prefix apps/notes
FROM caddy:2-alpine
COPY deploy/Caddyfile /etc/caddy/Caddyfile
COPY --from=build /app/dist /srv/site
COPY --from=build /app/apps/notes/dist /srv/notes
COPY --from=build /app/dist/portal/index.html /srv/home/index.html
COPY --from=build /app/public/portal /srv/home/portal
COPY --from=build /app/public/favicon.svg /srv/home/favicon.svg

第一阶段使用 Node.js:npm ci 根据 lock 文件安装依赖,随后构建 Astro 和 React。第二阶段从 Caddy 镜像开始,只复制生成后的文件。

因此,最终的 web 容器中不需要保留前端构建用的 Node.js、源码和 node_modules。这正是 Docker 多阶段构建 在本项目中的作用。

Go API 也是同样的思路。下面是实际使用的 Dockerfile:

services/api/Dockerfile
FROM golang:1.26-alpine AS build
RUN apk add --no-cache gcc musl-dev
WORKDIR /app
COPY services/api/go.mod services/api/go.sum ./
RUN go mod download
COPY services/api/ ./
RUN CGO_ENABLED=1 go build -trimpath -ldflags='-s -w' -o /out/api ./cmd/api
FROM alpine:3.23
RUN apk add --no-cache ca-certificates sqlite \
&& addgroup -g 10001 app \
&& adduser -D -u 10001 -G app app \
&& mkdir /data \
&& chown app:app /data
COPY --from=build /out/api /usr/local/bin/api
USER app
ENV API_ADDR=:8080 DATABASE_PATH=/data/personal.db GOMEMLIMIT=256MiB
EXPOSE 8080
ENTRYPOINT ["/usr/local/bin/api"]

这里的几个细节有具体原因:

配置或命令 作用
gcc musl-dev、CGO_ENABLED=1 当前使用的 SQLite 驱动需要 CGO,构建时准备 C 编译环境
go mod download 下载 Go 依赖,先复制依赖文件也有利于利用构建缓存
-trimpath、-ldflags='-s -w' 去除部分构建路径和调试信息
ca-certificates 为程序访问 HTTPS 服务提供 CA 证书
sqlite 提供命令行工具,用于在线备份数据库
USER app 让 API 以普通用户运行
EXPOSE 8080 声明服务端口,本身不会把端口映射到公网

Compose:把端口、数据卷和资源限制写下来

单个 Dockerfile 只负责镜像,compose.yaml 负责描述这两个服务如何一起运行。

以下是生产 Compose 的核心节选,省略了构建参数、部分认证配置、安全选项和日志配置;完整配置仍以项目文件为准:

compose.yaml(节选)
services:
web:
image: ${WEB_IMAGE}
restart: unless-stopped
ports: ["80:80", "443:443", "443:443/udp"]
environment:
HOME_DOMAIN: ${HOME_DOMAIN}
SITE_DOMAIN: ${SITE_DOMAIN}
NOTES_DOMAIN: ${NOTES_DOMAIN}
ACME_EMAIL: ${ACME_EMAIL}
volumes:
- caddy_data:/data
- caddy_config:/config
depends_on:
api:
condition: service_healthy
mem_limit: 192m
cpus: 0.75
api:
image: ${API_IMAGE}
restart: unless-stopped
environment:
API_ADDR: :8080
APP_ORIGIN: https://${NOTES_DOMAIN}
DATABASE_PATH: /data/personal.db
ALLOWED_EMAILS: ${ALLOWED_EMAILS}
GOOGLE_LOGIN_ENABLED: "false"
GOMEMLIMIT: 256MiB
GOMAXPROCS: "2"
volumes:
- notes_data:/data
mem_limit: 384m
cpus: 1.0
healthcheck:
test: ["CMD", "wget", "-q", "-O", "/dev/null", "http://127.0.0.1:8080/healthz"]
interval: 30s
timeout: 5s
retries: 3
start_period: 10s
volumes:
notes_data:
caddy_data:
caddy_config:

公网只开放 web 容器的入口。API 没有配置 ports,Caddy 通过 Compose 网络中的服务名 api 访问它,浏览器不需要直接连接服务器的 8080 端口。443/udp 用于 HTTP/3,常规 HTTPS 使用 443/tcp。

restart: unless-stopped 让容器在异常退出后自动重启;要在服务器重启后恢复服务,还需要 Docker 服务本身开机启动。

mem_limit 和 cpus 是资源上限,不表示容器一启动就会占满这些资源。GOMEMLIMIT 是 Go 运行时的软内存限制,也不能替代容器总内存限制。这次给 API 留出 384 MB 的容器上限,同时把 Go 的软限制设为 256 MiB。

健康检查会访问 API 的 /healthz。depends_on 配合 service_healthy,让启动流程等 API 健康后再启动 web;它并不是运行过程中持续联动重启两个服务的机制。

生产配置还给日志加了轮转限制,避免日志一直增长:

compose.yaml(节选)
logging:
driver: json-file
options:
max-size: "10m"
max-file: "3"

对 2 核 2 GB 的机器,Docker 是否合适,最终要看应用负载和实际监控,不能只看容器数量。这里通过静态化、移出构建过程和限制资源,控制服务器上的常驻负担。

SQLite 为什么不会随着发布被清空

数据库路径是 /data/personal.db,而 API 容器的 /data 挂载了 notes_data 卷。数据库实际保存在宿主机上由 Docker 管理的存储中,不在应用镜像里。

生产环境固定 Compose 项目名为 personal-studio,实际的数据卷名称是:

personal-studio_notes_data

发布新版本时,旧容器被替换,新容器继续挂载同一个卷。镜像版本改变,数据库文件不跟着替换。Docker 文档也明确区分了容器和卷的生命周期。

因此,重复发布不会自动清空笔记。已设置的密码也保存在数据库里,应用启动时发现账号已经初始化,就不会重新设置默认密码。

这里有两个容易误操作的地方:一是不要在日常发布时执行带 -v 的 docker compose down,它会删除声明的命名卷;二是不要随意更换 Compose 项目名,否则可能挂载到另一套新卷,看起来像数据丢了。

持久化也不等于备份。误删除、数据库损坏或整块磁盘丢失,仍然需要另外的恢复手段。

配置域名,再让 Caddy 接管 HTTPS

这次添加了三条 A 记录,记录值都指向服务器公网 IP:

主机记录 对应域名
@ example.com
blog blog.example.com
note.app note.app.example.com

这里曾经把 note.app 写成 note,两者对应的是不同域名。解析配置需要和应用入口完全一致。

Caddy 根据域名分发请求。下面是路由核心节选,省略了完整配置中的安全响应头:

deploy/Caddyfile
{
email {$ACME_EMAIL}
}
{$HOME_DOMAIN} {
root * /srv/home
file_server
}
{$SITE_DOMAIN} {
root * /srv/site
file_server
}
{$NOTES_DOMAIN} {
@backend path /api/* /auth/*
handle @backend {
reverse_proxy api:8080
}
handle {
root * /srv/notes
try_files {path} /index.html
file_server
}
}

reverse_proxy api:8080 把认证和数据请求交给 Go。try_files 则让 React 的前端路由在直接访问或刷新时能回到 index.html。

这次使用 Caddy 默认的自动 HTTPS:域名需要正确解析,服务器的 80、443 端口需要可访问,且不能被其他服务占用。条件满足后,Caddy 会申请和续期证书,并处理 HTTP 到 HTTPS 的跳转。证书相关数据通过 caddy_data 卷持久化,避免每次重建容器都丢失。自动 HTTPS 文档解释了这些前提。

原服务器上有旧博客和 Nginx,所以切换前保留了旧配置和旧博客容器,验证新服务后才停用原来的入口:

终端命令
# 服务器执行:仅适用于确认要替换旧 Nginx 的这次迁移
systemctl stop nginx
systemctl disable nginx
systemctl enable docker

stop 停止当前服务,disable 取消开机启动;它们不会删除原配置。这个步骤的目的,是把 80、443 端口交给 Caddy。如果机器上还有其他依赖 Nginx 的站点,就不能照搬。

导航页、博客和笔记页面也通过构建参数配置了自己的备案号,并链接到备案查询入口。备案号应填写自己网站的实际信息;它属于页面的公开配置,不是服务器密码。

先跑通一次手动发布

服务器的部署目录固定为 /opt/personal-studio。生产 .env 存放域名、允许登录的账号、镜像版本等配置。以下为格式示例,镜像标签需要填写实际构建出的 commit SHA:

.env(示例)
COMPOSE_PROJECT_NAME=personal-studio
HOME_DOMAIN=example.com
SITE_DOMAIN=blog.example.com
NOTES_DOMAIN=note.app.example.com
ACME_EMAIL=owner@example.com
ALLOWED_EMAILS=owner@example.com
GOOGLE_LOGIN_ENABLED=false
WEB_IMAGE=personal-studio-web:实际的完整commit-SHA
API_IMAGE=personal-studio-api:实际的完整commit-SHA

生产 .env 不提交到 Git,并限制文件权限:

终端命令
# 服务器执行,文件已经准备好之后
cd /opt/personal-studio
chmod 600 .env

600 表示只有文件所有者可以读写。公开站点标题等前端参数需要在构建时提供;修改服务器 .env 不会自动改写已经生成的静态页面。

最初的发布方式是 GitHub Actions 构建镜像,本机下载工件,再通过 SSH 完成服务器上的切换:

终端命令
# 本机执行,替换成实际运行 ID 和完整 commit SHA
gh run download RUN_ID \
--repo example-user/personal-studio \
--name release-COMMIT \
--dir .cache/release-COMMIT

这条命令使用 GitHub CLI 下载一次构建的发布文件。文件到达服务器后,核心操作是:

终端命令
# 服务器执行:在包含镜像文件和校验清单的发布目录中
sha256sum -c SHA256SUMS
docker load -i images.tar.gz
# 将生产 .env 的两个镜像标签更新到该版本后
cd /opt/personal-studio
docker compose --project-name personal-studio config --quiet
docker compose --project-name personal-studio up \
-d --no-build --wait --wait-timeout 120

各条命令分别解决一件事:

命令或参数 作用
sha256sum -c 核对文件内容是否与发布清单一致
docker load 把归档中的镜像导入服务器 Docker
config --quiet 检查 Compose 配置及变量解析,不打印展开后的敏感配置
--project-name personal-studio 固定服务和数据卷所属的项目
up -d 在后台创建或更新容器
--no-build 不在服务器上编译,使用已经准备好的镜像
--wait 等待服务运行;有健康检查的服务需要达到健康状态
--wait-timeout 120 设置上述等待的超时时间

up 在配置或镜像变化时会重建相关容器,并保留挂载卷;具体选项见 Compose up 文档。这套单实例方案更新时可能有短暂中断,并没有实现零停机发布。

把 SSH 配置交给 GitHub Actions

本机的 ssh blog 只是 ~/.ssh/config 中的别名。GitHub runner 不认识这个别名,需要单独配置地址、用户、端口和认证密钥。

我为自动部署生成了一把专用密钥:

终端命令
# 本机执行;如果同名文件已经存在,不要直接覆盖
ssh-keygen -t ed25519 \
-C "github-actions-personal-studio" \
-f ~/.ssh/personal-studio-actions \
-N ""

-t 指定密钥算法,-C 添加用途备注,-f 指定保存位置,-N "" 表示不设置口令,以便自动化使用。私钥留给 GitHub Secrets,公钥加入服务器:

终端命令
# 本机执行,blog 是本机已经配置好的服务器别名
cat ~/.ssh/personal-studio-actions.pub | ssh blog \
'umask 077; mkdir -p ~/.ssh; cat >> ~/.ssh/authorized_keys; chmod 700 ~/.ssh; chmod 600 ~/.ssh/authorized_keys'

authorized_keys 列出允许登录的公钥。这里使用追加,保留原来的登录密钥;这条命令执行一次即可。

然后测试新密钥。下面的 IP 和端口都是示例,用户名也要换成实际部署用户:

终端命令
ssh -p 22222 \
-i ~/.ssh/personal-studio-actions \
-o IdentitiesOnly=yes \
-o PasswordAuthentication=no \
deploy@203.0.113.10 'echo connected'

IdentitiesOnly 让 SSH 使用指定身份,禁用密码认证可以确认这次确实依靠密钥连接。输出 connected 才表示测试成功。

接下来,在仓库的 Settings → Secrets and variables → Actions 中配置:

Secret 内容
DEPLOY_HOST 服务器地址
DEPLOY_USER 部署用户名
DEPLOY_PORT 实际 SSH 端口,不要默认认为是 22
DEPLOY_SSH_KEY 专用私钥的完整内容
DEPLOY_KNOWN_HOSTS 服务器 SSH 主机公钥记录

在 Mac 上,可以用 pbcopy < ~/.ssh/personal-studio-actions 将私钥复制到剪贴板,再粘贴到 Secret 输入框。不要把私钥放进源码或构建日志。

主机公钥用于确认连接的是正确的服务器。通过已经信任的 SSH 连接读取,生成示例记录:

终端命令
# 本机执行:将示例地址、端口替换为实际值
ssh blog \
"awk '{print \"[203.0.113.10]:22222\", \$1, \$2}' /etc/ssh/ssh_host_ed25519_key.pub" \
| pbcopy

非默认端口的记录需要使用 [地址]:端口 格式。这次就曾经漏掉真实端口,需要同时修正 DEPLOY_PORT 和 DEPLOY_KNOWN_HOSTS。

Actions 连接时启用 StrictHostKeyChecking=yes,按保存的主机记录校验,不通过关闭校验来绕过错误。Secrets 的设置方式可以查阅 GitHub 官方文档。

从自动构建到自动部署

最终的工作流分成 release 和 deploy 两个 job。前者测试、构建,后者依赖前者成功,再执行上线。

构建 job 中运行的检查包括:

终端命令
# 仓库根目录
python3 -m unittest discover -s deploy -p 'test_*.py'
npm ci
npm ci --prefix apps/notes
npm run notes:test
# Go API 目录
cd services/api
go test -race ./...
go vet ./...

Python 测试覆盖下载文件重组、备份失败时不更新容器、健康检查失败时恢复旧配置等行为。go test -race 检查测试执行过程中的数据竞争,go vet 做静态检查。Astro 的类型检查、构建和站内链接检查则在 web 镜像构建时执行。

构建 API 镜像的实际命令是:

终端命令
# GitHub Actions runner 中,从仓库根目录执行
docker buildx build \
--platform linux/amd64 \
--load \
-f services/api/Dockerfile \
-t personal-studio-api:${GITHUB_SHA} .

--platform 与服务器 CPU 架构保持一致,--load 把结果加载进 runner 的 Docker,-f 选择 Dockerfile,-t 使用完整 commit SHA 作为版本标签。末尾的 . 是构建上下文,即仓库根目录。

web 镜像使用相同方法,但选择 deploy/Dockerfile.web,并通过 --build-arg 传入站点域名、名称、作者和备案号。这些参数会影响最终静态文件。

两个镜像随后导出为发布文件:

终端命令
mkdir -p release
docker save \
personal-studio-api:${GITHUB_SHA} \
personal-studio-web:${GITHUB_SHA} \
| gzip > release/images.tar.gz
cp compose.yaml deploy/release.py release/
printf '%s\n' "${GITHUB_SHA}" > release/revision.txt
cd release
sha256sum images.tar.gz compose.yaml release.py revision.txt > SHA256SUMS

docker save 导出镜像,gzip 压缩,revision.txt 记录版本,校验清单覆盖镜像和部署文件。这次没有接入 Docker Hub 或其他镜像仓库,而是用 GitHub Actions artifact 保存发布包,保留期为 14 天。

部署 job 使用当前运行的临时 GitHub token 获取工件下载链接。它只把短期签名链接通过 SSH 标准输入传给服务器,不把 GitHub token 放在服务器上,也不把签名链接打印到日志。

服务器依次执行:下载、完整性校验、导入镜像、备份数据库与配置、更新镜像标签、启动容器、检查三个站点和未登录访问限制。最后写入已部署版本号。

真正花时间的地方:跨境传输

第一次自动部署没有卡在 Docker,而是卡在镜像传输。

直接从 GitHub runner 用 SCP 上传大约 29 MB 的镜像,速度很慢。改成让服务器单连接下载 GitHub 工件,仍然不理想。为了避免长时间上传最终超时,这两次尝试都在容器切换前取消,原站点继续运行。

最终给下载脚本增加了分段并行处理:每段 512 KiB,最多 16 路并发;检查服务器确实返回指定的 HTTP Range,按顺序拼接,再通过 ZIP 和 SHA256 校验后才允许部署。

用已有工件做的一次实测,约 29 MB 文件在 248 秒内下载完成。后续完整的 Actions 自动发布也成功了。这是当时网络条件下的结果,不代表固定速度;并发也并非越高越好,服务器带宽和远端限制仍然存在。

这段经历让我意识到,部署流程除了“怎样构建”,还必须验证“产物怎样到达服务器”。只在本机能下载成功,不代表 GitHub runner 到服务器的传输路径也顺畅。

发布前备份,失败时恢复旧镜像

数据库启用了 WAL 模式,不能假设运行时只复制一个主数据库文件就能得到完整备份。这次使用 SQLite 的在线备份能力,下面是等价的手工操作:

终端命令
# 服务器执行;子 shell 内遇到错误就停止,不继续删除临时备份
(
set -e
cd /opt/personal-studio
umask 077
mkdir -p backups
backup_stamp=$(date +%Y%m%d-%H%M%S)
docker compose --project-name personal-studio exec -T api \
sqlite3 /data/personal.db ".backup /data/backup-${backup_stamp}.db"
docker compose --project-name personal-studio cp \
"api:/data/backup-${backup_stamp}.db" \
"backups/notes-${backup_stamp}.db"
# 复制成功后,删除容器卷中的临时备份
docker compose --project-name personal-studio exec -T api \
rm "/data/backup-${backup_stamp}.db"
chmod 600 "backups/notes-${backup_stamp}.db"
)

exec -T 在运行中的 API 容器里执行命令,不分配交互终端;.backup 生成数据库快照,compose cp 再将备份复制到宿主机的备份目录。在线备份的机制可以参考 SQLite 文档。

自动发布还会保存旧 .env 和旧 compose.yaml。备份失败就停止发布;更新后的健康检查失败,则恢复旧配置,再运行旧镜像,同时将 Actions 标记为失败。

这里的“自动回滚”有明确边界:它恢复应用镜像和配置,不自动覆盖数据库。新版本如果已经进行了不兼容的数据库迁移,单纯回退镜像可能无法恢复服务,必须另行设计迁移和数据恢复方案。

另外,当前备份还保存在同一台服务器上,没有异地副本,也没有独立的定时备份任务。发布前备份能帮助处理发布故障,但不能覆盖服务器或磁盘整体丢失的情况。

怎样确认真的上线成功

Actions 显示绿色之后,又做了一轮独立检查:

终端命令
# 服务器执行
cd /opt/personal-studio
docker compose --project-name personal-studio ps
docker compose --project-name personal-studio logs --tail 60 api web
docker stats --no-stream
cat deployed-revision.txt

ps 确认容器和健康状态,logs 查看最近日志,stats 观察当前资源使用,版本文件用来确认实际完成部署的 commit。这些检查各有侧重,容器正在运行并不等于页面和接口就一定正确。

从服务器外部再访问站点:

终端命令
curl -sS -o /dev/null -w '%{http_code}\n' https://example.com/
curl -sS -o /dev/null -w '%{http_code}\n' https://blog.example.com/
curl -sS -o /dev/null -w '%{http_code}\n' https://note.app.example.com/

-sS 隐藏进度但保留错误信息,-o /dev/null 丢弃正文,-w 输出状态码。三个入口都返回了 200;不带登录信息访问受保护的用户接口返回 401。还核对了 API 挂载的仍然是原数据卷,并检查发布前备份的 SQLite 完整性和文件权限。

这些属于上线冒烟检查。它们确认基本可用性和访问限制,不代替完整的浏览器登录、改密和笔记编辑测试。

上线之后,把日常开发放到 dev

自动部署完成后,main 的含义也改变了:代码推上去,就可能更新生产环境。因此从当前稳定版本建立了 dev 分支:

终端命令
# 本机执行,首次创建分支时使用
git fetch origin main
git switch -c dev origin/main
git push -u origin dev

之后日常开发在 dev,准备发布时再通过 PR 合并到 main。当前工作流只监听 main 的 push;单纯推送 dev 不会自动构建或部署。手动运行工作流时,非 main 分支可以构建,但部署 job 会跳过。

工作流还关闭了“新推送自动取消正在运行的发布”,服务器端也加了发布锁,避免两个任务同时切换容器。独立的文档目录修改可以被忽略,但博客文章属于网站内容,合并到 main 后需要重新构建。

最终得到的是一条可以重复执行的路径:在 dev 写代码和内容,确认后合并到 main,由 GitHub Actions 完成测试、构建、传输、备份和上线。服务器持续保留数据,应用版本则可以明确追溯到某次提交。