Docker 部署 Quick Reference：自托管开发者速查站点

Quick Reference 是面向开发者的技术速查站点，按编程语言、工具、数据库、Docker、键盘快捷键等主题组织 Markdown 速查内容。中文仓库 jaywcjlove/reference 提供当前 Docker 发布链路，仓库版本为 1.48.0，官方 CI 构建 wcjiang/reference 镜像；英文仓库 Fechin/reference 是英文内容对照项目，README 指向 cheatsheets.zip，不应与中文镜像混用。

本文使用 wcjiang/reference:1.48.0 和 Docker Compose 部署一个无状态静态站点。Quick Reference 不需要数据库、缓存、账号或运行时上传目录，站点内容在镜像构建阶段生成；部署目录只保存 Compose 配置和运维记录。主路径适合长期运行，更新时通过更换镜像 tag 进行可回滚升级。

部署结论

项目	本文采用的值
项目地址	jaywcjlove/reference
中文项目地址	jaywcjlove/reference
英文对照项目	Fechin/reference
官方镜像	wcjiang/reference
项目版本	1.48.0
主部署方法	官方镜像 Docker Compose 单服务
备选方法	官方镜像 docker run
维护范围	maintained：无状态站点，仍需固定版本、更新验收和回滚
对外端口	默认绑定 127.0.0.1:9667:3000
持久化位置	无业务数据卷；保存 compose.yaml 和反向代理配置
依赖服务	无数据库、缓存或外部队列
镜像构建平台	官方 CI 声明构建 linux/amd64、linux/arm64
部署日期	2026-09-28

中文仓库的 CI 使用仓库内 Dockerfile 构建静态文件，再发布 wcjiang/reference:latest 和版本标签。生产部署使用固定版本标签 1.48.0，避免主路径隐式跟随 latest；如果 Docker Registry 尚未提供该版本 tag，应先确认镜像发布状态，再改用已存在的固定 tag，不要直接把 latest 当成可回滚版本。

架构说明

Mermaid 流程图

正在准备渲染...

查看源码

flowchart LR
  Browser[浏览器] -->|127.0.0.1:9667| Host[宿主机端口]
  Host -->|容器端口 3000| Web[wcjiang/reference:1.48.0]
  Web --> Assets[镜像内静态 HTML/CSS/JS/图片]
  Proxy[反向代理] -.->|公网 HTTPS 时| Host

镜像只提供静态网页服务。Dockerfile 以 wcjiang/docker-static-website 为基础镜像，把 dist/ 复制到静态服务器目录；仓库 CI 在构建阶段执行 npm run build 和静态资源复制。运行时没有数据库迁移、账号初始化或文件上传，容器重建不会影响站点内容，也不会保存用户输入。

不要把英文仓库的 cheatsheets.zip 域名、内容路径或构建产物写入中文镜像配置。中文镜像的来源、镜像名称和容器端口以 jaywcjlove/reference 的 Docker 文档与 CI 为准。

前置条件

• Docker Engine 与 Docker Compose v2 可用。
• 宿主机 9667 端口未占用；需要其他端口时只修改宿主机端口一侧。
• 如果通过公网访问，准备独立域名和 HTTPS 反向代理；本文不把容器端口直接暴露到公网。
• 目标架构属于官方 CI 声明的 linux/amd64 或 linux/arm64，其他架构先自行构建并完成静态检查。

docker version
docker compose version

预期能看到 Docker Engine 和 Compose v2 的版本号。如果只安装了旧版 docker-compose，先升级 Compose 插件，避免把 v1 命令和 v2 配置混用。

Docker Compose 正式部署

准备目录

创建一个只保存部署配置的目录。Quick Reference 没有需要挂载的业务数据目录，不要为了“持久化”创建空卷并误以为卷中保存了站点内容。

sudo mkdir -p /opt/quickreference
sudo chown -R "$USER":"$USER" /opt/quickreference
cd /opt/quickreference

写入 Compose 配置

创建 compose.yaml：

services:
  quickreference:
    image: wcjiang/reference:1.48.0
    restart: unless-stopped
    ports:
      - "127.0.0.1:9667:3000"

宿主机只监听回环地址，方便先通过本机浏览器或反向代理验收。若应用和反向代理运行在同一台主机，代理连接 127.0.0.1:9667；如果必须让局域网直接访问，再把宿主机地址改成受控内网地址，并用防火墙限制来源。

检查配置并启动

docker compose config --quiet
docker compose pull quickreference
docker compose up -d quickreference
docker compose ps

config --quiet 返回状态码 0 表示配置可解析。pull 应显示 wcjiang/reference:1.48.0，不要在这里改成 latest。启动后服务状态应为 Up；如果容器立即退出，先查看日志和端口占用，不要反复删除并重建容器：

docker compose logs --tail=120 quickreference
docker ps --format 'table {{.Names}}\t{{.Ports}}\t{{.Status}}'

备选：官方镜像 docker run

中文仓库 CI 生成的 Docker 说明同时给出了单容器命令。该方法适合临时体验或只需要一条命令的场景，参数与 Compose 主路径相同：

docker pull wcjiang/reference:1.48.0
docker run --name quickreference \
  --restart unless-stopped \
  -p 127.0.0.1:9667:3000 \
  wcjiang/reference:1.48.0

长期运行仍建议保留 compose.yaml，因为 Compose 文件能明确记录镜像版本、端口和重启策略。docker run --rm 只适合临时体验；容器删除后不会丢失业务数据，但需要重新执行命令才能恢复站点。

验证部署结果

配置层

docker compose config --quiet
docker compose config --images

预期第一个命令返回状态码 0，第二个命令只列出 wcjiang/reference:1.48.0。如果出现其他镜像名，说明当前 Compose 文件不是本文主路径。

容器状态层

docker compose ps
docker inspect --format '{{.State.Status}} {{.State.ExitCode}}' "$(docker compose ps -q quickreference)"

预期服务状态为 Up，进程状态为 running 0。本文不把 healthy 作为成功信号，因为官方 Docker 说明没有为该镜像声明可依赖的 HEALTHCHECK；应用响应检查是必要的协议层验收。

HTTP 响应层

curl -fsS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:9667/
curl -fsS http://127.0.0.1:9667/ | sed -n '1,12p'

预期第一个命令输出 200，第二个命令能看到 Quick Reference 页面 HTML。浏览器访问 http://127.0.0.1:9667/ 后，应能打开中文速查目录和静态资源。

日志层

docker compose logs --tail=120 quickreference

预期日志中没有持续的启动错误；静态服务器的访问日志可能因基础镜像配置不同而输出到标准输出或保持为空。日志为空不代表 HTTP 失败，以 curl 的 200 和浏览器静态资源加载结果为准。

重建验收

Quick Reference 没有运行时数据，重建验收关注站点是否可以重新拉起：

docker compose down
docker compose up -d quickreference
curl -fsS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:9667/

预期服务重新启动且 HTTP 返回 200。docker compose down 不会删除 compose.yaml，也不存在需要从卷恢复的数据库或用户内容。

首次初始化与访问入口

Quick Reference 是静态站点，没有管理员账号、注册流程、运行时配置页或数据库初始化。首次访问直接打开：

http://127.0.0.1:9667/

公网使用时，把域名反向代理到宿主机的 127.0.0.1:9667，在代理层终止 TLS，并确认 /、CSS、JavaScript、字体和图片等静态资源都能返回 200。不要把容器端口直接暴露到公网，也不要把站点误部署到 /reference 子路径，除非先验证构建产物中的绝对路径和代理重写规则。

日常运维

cd /opt/quickreference
docker compose ps
docker compose logs --tail=120 quickreference
docker compose restart quickreference

镜像无状态，日常运维重点是记录当前 tag、镜像 ID、域名代理配置和构建来源。站点内容更新由项目发布镜像完成，不能在运行容器内直接编辑 HTML 作为长期变更。

备份与恢复

Quick Reference 没有数据库、上传文件或运行时内容，部署备份单元是：

• /opt/quickreference/compose.yaml；
• 反向代理的站点配置和证书续期配置；
• 当前使用的镜像 tag，以及变更记录中对应的项目版本。

如果使用项目源码自行构建，还要保存 package.json、锁文件、Dockerfile、源代码提交和构建输出策略。恢复时重新创建部署目录和 Compose 文件，拉取相同镜像 tag 后执行：

docker compose up -d quickreference
curl -fsS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:9667/

恢复验收是首页、一个主题页面、CSS/JavaScript/图片资源均能正常返回；没有账号、数据库或页面编辑记录需要恢复。通用 Docker 配置归档和主机级备份方法见 Docker 镜像数据备份和恢复教程。

升级与回滚

升级前记录当前镜像 ID 和访问结果，再拉取目标版本：

docker image inspect wcjiang/reference:1.48.0 --format '{{.Id}}'
docker compose pull quickreference
docker compose up -d quickreference
docker compose ps
curl -fsS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:9667/

升级验收需要确认容器重新处于 Up、首页返回 200、主要静态资源没有 404。如果版本 tag 已变更或镜像拉取失败，不要自动改用 latest；先检查项目 release 和 Docker Hub 标签。

回滚时把 compose.yaml 的 image 改回上一个已验证的固定 tag，再执行：

docker compose pull quickreference
docker compose up -d quickreference

由于服务无状态，回滚不涉及数据库迁移；如果使用了自定义源码构建，必须同时回退构建提交和镜像。删除容器或执行 docker compose down 不会删除 Compose 文件，但删除部署目录会丢失版本记录和反向代理配置。

通用更新、回滚和卸载流程见 Docker Compose 服务更新、回滚与卸载教程。

生产环境安全加固

• 宿主机默认绑定 127.0.0.1:9667，公网访问通过 HTTPS 反向代理，防火墙不直接放行容器端口。
• 镜像没有账号和写接口，安全重点是镜像来源、版本固定、主机 Docker 权限和代理配置。
• 使用版本 tag，不把 latest 作为可审计的生产版本；发布前检查镜像仓库和项目 CI 的 tag 对应关系。
• 只允许必要的反向代理路径和方法，限制管理主机访问 Docker Socket 的用户；不要把 Docker Socket 挂载进 Quick Reference 容器。
• 如果通过公网提供站点，开启 TLS、设置安全响应头并限制代理到源站的来源；通用配置见 Docker 服务反向代理与 HTTPS 教程。
• 通用容器端口、镜像供应链、日志和主机权限基线见 Docker Compose 生产安全加固教程。

常见问题

浏览器访问被拒绝

检查容器是否处于 Up、宿主端口是否仍为 9667，以及是否把容器端口误写成 9667。Quick Reference 的官方 Docker 命令是宿主端口 9667 映射到容器端口 3000。

docker compose config 通过但页面打不开

先执行 docker compose ps 和 docker compose logs --tail=120 quickreference，再执行 curl http://127.0.0.1:9667/。Compose 只证明配置可解析，不证明镜像已成功拉取或静态服务器正在监听；如果容器启动后退出，检查镜像 tag、CPU 架构和宿主端口占用。

拉取 wcjiang/reference:1.48.0 失败

先确认 Docker Hub 网络可达和 tag 是否存在，再检查目标架构是否为官方 CI 构建的平台。不要因为固定 tag 拉取失败就无提示地切换到 latest；需要临时验证时可以使用项目 CI 明确发布的 latest，并在记录中标注实际版本和回滚限制。

页面能打开但 CSS 或图片返回 404

先直接访问 http://127.0.0.1:9667/ 排除反向代理路径重写问题，再查看浏览器 Network 和代理日志。Quick Reference 是按根路径构建的静态站点，挂载到 /reference 子路径可能导致资源绝对路径失效；优先使用独立域名或独立端口。

想修改速查内容

不要在运行容器内直接编辑生成的 dist 文件。Fork jaywcjlove/reference，按仓库的 npm install、npm run build 生成静态产物，再依据项目 Dockerfile 构建自己的镜像；构建完成后固定自己的镜像 tag，并把源码提交、构建命令和镜像 tag 一起记录。

中文和英文版本应该使用哪个镜像

本文镜像 wcjiang/reference 对应中文仓库 jaywcjlove/reference。英文仓库 Fechin/reference README 指向 cheatsheets.zip，没有在本文证据中确认与 wcjiang/reference 相同的镜像发布链路；需要英文内容时，应按英文仓库自己的构建说明生成镜像，不要把两个项目的内容和 tag 混合。

总结

Quick Reference 的 Docker 部署是一个无状态静态站点：使用 wcjiang/reference:1.48.0、宿主机 127.0.0.1:9667 到容器 3000 的映射和一个 Compose 服务即可运行。验收重点是 Compose 配置、容器进程、HTTP 200 和静态资源加载；备份重点是 Compose 与反向代理配置，恢复和回滚只需要重新拉取已验证的固定镜像。中文仓库负责本文镜像来源，英文仓库只作为内容对照，不应混用发布链路。

参考资料

• jaywcjlove/reference
• jaywcjlove/reference Dockerfile
• jaywcjlove/reference CI
• Fechin/reference
• wcjiang/reference Docker 镜像
• Docker Compose CLI reference
• Docker run reference