简单文档

部署服务

部署 Estel Docs、微信签名服务与相关运维配置。

部署模式

Estel Docs 支持两类部署方式：

SSR Docker 部署：运行 Nuxt server 产物，适合当前项目的完整能力。
静态生成部署：使用 pnpm generate 输出静态文件，适合纯文档托管；微信签名等动态接口需要独立服务配合。

当前仓库已经提供 Dockerfile 与 GitHub Actions，更推荐使用 SSR Docker 部署。

SSR Docker 部署

构建镜像

docker build -t estel-docs:latest .

运行容器

docker run --rm -p 3000:3000 estel-docs:latest

容器内默认：

NODE_ENV=production
HOST=0.0.0.0
PORT=3000
运行命令：node .output/server/index.mjs

Dockerfile 结构

阶段	基础镜像	作用
`deps`	`node:22-bookworm`	安装 pnpm 依赖，便于缓存复用。
`builder`	`node:22-bookworm`	安装 Playwright Chromium，并执行 `pnpm build`。
`production`	`node:22-alpine`	复制 `.output`，以 `node` 用户运行服务。

Playwright Chromium 主要用于 OG 图片渲染，因此构建阶段会安装浏览器及其系统依赖。

静态生成部署

pnpm generate

生成产物位于 .output/public。可以部署到 Nginx、对象存储、CDN 或其他静态托管平台。

npx serve .output/public

静态部署只能托管前端资源。微信 JS-SDK 签名接口 /api/wechat/js-sign 仍需要由 wechat-sign-server 或其他后端服务提供，并通过反向代理暴露到同源路径。

路由与预渲染

nuxt.config.ts 中的路由规则：

路由	行为
`/`	预渲染。
`/docs/**`	预渲染。
`/blog/**`	预渲染。
`/raw/**`	关闭 SSR，不预渲染。

Nitro prerender 开启 crawlLinks 与 failOnError，因此内容链接错误可能导致构建失败。

安全响应头

项目为全部路由配置了常见安全响应头：

Content-Security-Policy
Strict-Transport-Security
X-Frame-Options
X-Content-Type-Options
Referrer-Policy
Permissions-Policy

同时 server/plugins/security-headers.ts 会移除 X-Powered-By 响应头。

CSP 允许 https://res.wx.qq.com，这是微信 JSSDK 所需脚本来源。

微信签名服务部署

微信分享能力由独立 Go 服务提供，目录为 wechat-sign-server/。

关键接口

GET /health
POST /api/wechat/js-sign

关键环境变量

APP_ENV=production
PORT=8090
WECHAT_APP_ID=your_wechat_app_id
WECHAT_APP_SECRET=your_wechat_app_secret
ALLOWED_ORIGINS=https://lijue.net,https://www.lijue.net
ALLOWED_DOMAINS=lijue.net,www.lijue.net
TOKEN_CACHE_SECONDS=7000
TICKET_CACHE_SECONDS=7000
REQUEST_TIMEOUT_SECONDS=8
LOG_LEVEL=info

Nginx 反代示例

location /api/wechat/ {
    proxy_pass http://127.0.0.1:8090/api/wechat/;
    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;
}

完整说明见仓库根目录下的 wechat-sign-server/README.md。

CI/CD

GitHub Actions 工作流位于 .github/workflows/ci.yml。

当前流程：

lint：安装依赖并运行 pnpm run lint。
typecheck：安装依赖并运行 pnpm run typecheck。
go-test：进入 wechat-sign-server/ 运行 go test ./...。
build：在上述任务通过后使用 Docker Buildx 构建镜像。
main 分支 push 时：
- 登录私有镜像仓库。
- 推送 latest 与 commit SHA 标签。
- 触发 Coolify 部署接口。

Docker build 开启：

GitHub Actions cache
provenance
SBOM

依赖更新

Renovate 配置位于 renovate.json：

继承 Nuxt preset。
维护 v1 与 main 分支。
开启 lockfile maintenance。
更新后执行 pnpm dedupe。

生产检查清单

pnpm lint 通过。
pnpm typecheck 通过。
wechat-sign-server 的 go test ./... 通过。
Docker 镜像可以正常构建并启动。
生产环境 Secret 未写入仓库。
微信公众号后台配置了 JS 安全域名。
/api/wechat/js-sign 能从站点同源访问。
OG 图片在目标页面可正常生成。
CSP 未阻止必要脚本、图片或接口。

可扩展运维能力

后续可以加入：

Docker HEALTHCHECK。
镜像漏洞扫描，例如 Trivy。
依赖审计与 CodeQL/SAST。
Sitemap 与 robots.txt 生成。
RSS/Atom Feed。
Lighthouse CI。
Sentry 或其他错误追踪。
结构化日志与运行指标。
PR 预览环境或 staging 环境。

编辑页面 or 提交问题