部署笔记:在 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 描述如何生成镜像。镜像是可以部署的程序包,容器则是镜像启动后的运行实例。
前端镜像使用多阶段构建。下面是结构节选,省略了实际文件中的站点名称、备案号等构建参数:
FROM node:24-alpine AS buildWORKDIR /appCOPY package.json package-lock.json ./RUN npm ciCOPY . .RUN npm ci --prefix apps/notes \ && npm run build \ && npm run build --prefix apps/notes
FROM caddy:2-alpineCOPY deploy/Caddyfile /etc/caddy/CaddyfileCOPY --from=build /app/dist /srv/siteCOPY --from=build /app/apps/notes/dist /srv/notesCOPY --from=build /app/dist/portal/index.html /srv/home/index.htmlCOPY --from=build /app/public/portal /srv/home/portalCOPY --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:
FROM golang:1.26-alpine AS buildRUN apk add --no-cache gcc musl-devWORKDIR /appCOPY services/api/go.mod services/api/go.sum ./RUN go mod downloadCOPY services/api/ ./RUN CGO_ENABLED=1 go build -trimpath -ldflags='-s -w' -o /out/api ./cmd/api
FROM alpine:3.23RUN apk add --no-cache ca-certificates sqlite \ && addgroup -g 10001 app \ && adduser -D -u 10001 -G app app \ && mkdir /data \ && chown app:app /dataCOPY --from=build /out/api /usr/local/bin/apiUSER appENV API_ADDR=:8080 DATABASE_PATH=/data/personal.db GOMEMLIMIT=256MiBEXPOSE 8080ENTRYPOINT ["/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 的核心节选,省略了构建参数、部分认证配置、安全选项和日志配置;完整配置仍以项目文件为准:
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;它并不是运行过程中持续联动重启两个服务的机制。
生产配置还给日志加了轮转限制,避免日志一直增长:
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 根据域名分发请求。下面是路由核心节选,省略了完整配置中的安全响应头:
{ 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 nginxsystemctl disable nginxsystemctl enable dockerstop 停止当前服务,disable 取消开机启动;它们不会删除原配置。这个步骤的目的,是把 80、443 端口交给 Caddy。如果机器上还有其他依赖 Nginx 的站点,就不能照搬。
导航页、博客和笔记页面也通过构建参数配置了自己的备案号,并链接到备案查询入口。备案号应填写自己网站的实际信息;它属于页面的公开配置,不是服务器密码。
先跑通一次手动发布
服务器的部署目录固定为 /opt/personal-studio。生产 .env 存放域名、允许登录的账号、镜像版本等配置。以下为格式示例,镜像标签需要填写实际构建出的 commit SHA:
COMPOSE_PROJECT_NAME=personal-studioHOME_DOMAIN=example.comSITE_DOMAIN=blog.example.comNOTES_DOMAIN=note.app.example.comACME_EMAIL=owner@example.comALLOWED_EMAILS=owner@example.comGOOGLE_LOGIN_ENABLED=falseWEB_IMAGE=personal-studio-web:实际的完整commit-SHAAPI_IMAGE=personal-studio-api:实际的完整commit-SHA生产 .env 不提交到 Git,并限制文件权限:
# 服务器执行,文件已经准备好之后cd /opt/personal-studiochmod 600 .env600 表示只有文件所有者可以读写。公开站点标题等前端参数需要在构建时提供;修改服务器 .env 不会自动改写已经生成的静态页面。
最初的发布方式是 GitHub Actions 构建镜像,本机下载工件,再通过 SSH 完成服务器上的切换:
# 本机执行,替换成实际运行 ID 和完整 commit SHAgh run download RUN_ID \ --repo example-user/personal-studio \ --name release-COMMIT \ --dir .cache/release-COMMIT这条命令使用 GitHub CLI 下载一次构建的发布文件。文件到达服务器后,核心操作是:
# 服务器执行:在包含镜像文件和校验清单的发布目录中sha256sum -c SHA256SUMSdocker load -i images.tar.gz
# 将生产 .env 的两个镜像标签更新到该版本后cd /opt/personal-studiodocker compose --project-name personal-studio config --quietdocker 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 cinpm ci --prefix apps/notesnpm run notes:test
# Go API 目录cd services/apigo 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 releasedocker save \ personal-studio-api:${GITHUB_SHA} \ personal-studio-web:${GITHUB_SHA} \ | gzip > release/images.tar.gzcp compose.yaml deploy/release.py release/printf '%s\n' "${GITHUB_SHA}" > release/revision.txtcd releasesha256sum images.tar.gz compose.yaml release.py revision.txt > SHA256SUMSdocker 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 -ecd /opt/personal-studioumask 077mkdir -p backupsbackup_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-studiodocker compose --project-name personal-studio psdocker compose --project-name personal-studio logs --tail 60 api webdocker stats --no-streamcat deployed-revision.txtps 确认容器和健康状态,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 maingit switch -c dev origin/maingit push -u origin dev之后日常开发在 dev,准备发布时再通过 PR 合并到 main。当前工作流只监听 main 的 push;单纯推送 dev 不会自动构建或部署。手动运行工作流时,非 main 分支可以构建,但部署 job 会跳过。
工作流还关闭了“新推送自动取消正在运行的发布”,服务器端也加了发布锁,避免两个任务同时切换容器。独立的文档目录修改可以被忽略,但博客文章属于网站内容,合并到 main 后需要重新构建。
最终得到的是一条可以重复执行的路径:在 dev 写代码和内容,确认后合并到 main,由 GitHub Actions 完成测试、构建、传输、备份和上线。服务器持续保留数据,应用版本则可以明确追溯到某次提交。