返回首页

Blog 部署以及踩坑

2025/7/21

•

技术, 学习

博客项目 Docker 部署到 VPS 全流程与常见坑总结

1. 环境准备

一台已安装 Docker 的 VPS（推荐 Ubuntu 22.04+）
域名（可选，建议绑定）
本地开发环境（建议 macOS/Linux，已安装 Node.js、Bun、Go）

2. 本地构建与准备

2.1 安装依赖

cd web
bun install

2.2 重要配置

Astro 配置：web/astro.config.mjs
必须加上 Vite 的 rollupOptions，避免生成 Go embed 不支持的文件名（如 _slug_ 开头的文件）。

export default defineConfig({
  integrations: [react(), tailwind()],
  vite: {
    build: {
      rollupOptions: {
        output: {
          entryFileNames: 'assets/entry-[hash].js',
          chunkFileNames: 'assets/chunk-[hash].js',
          assetFileNames: (assetInfo) => {
            if (assetInfo.name && assetInfo.name.endsWith('.css')) {
              return `assets/style-[hash][extname]`;
            }
            return `assets/[name]-[hash][extname]`;
          }
        }
      }
    }
  },
  // ... 其他配置
});

2.3 构建前端

cd web
bun run build

2.4 检查产物

确保 web/dist/assets/ 下有 style-xxx.css 这样的 CSS 文件。

3. Docker 镜像构建

3.1 Dockerfile 关键点

多阶段构建，先前端再后端
Go embed 语法必须为 //go:embed web/dist/**

Dockerfile 示例（核心部分）：

FROM oven/bun:alpine AS bun-builder
WORKDIR /app
COPY ./web/package.json ./web/bun.lock ./
RUN bun install --frozen-lockfile
COPY ./web .
RUN bun run build

FROM golang:1.23-alpine AS builder
WORKDIR /app
COPY go.mod go.sum main.go ./
COPY --from=bun-builder /app/dist ./web/dist/
RUN CGO_ENABLED=0 go build -ldflags '-s -w' -o main main.go

FROM alpine AS runner
WORKDIR /app
COPY --from=builder /app/main .
COPY --from=builder /app/web/dist ./web/dist
ENV HOST=0.0.0.0
ENV PORT=3000
EXPOSE 3000
CMD ["/app/main"]

3.2 构建镜像

docker build --no-cache -t myblog:latest .

4. 上传与部署

4.1 上传代码到 VPS

推荐用 scp、rsync 或直接 git clone。

4.2 在 VPS 上构建并运行

docker build --no-cache -t myblog:latest .
docker stop blog_server && docker rm blog_server
docker run -d --name blog_server -p 80:3000 myblog:latest

5. 访问与验证

直接访问 http://your_vps_ip/ 或绑定的域名
页面应能正常渲染，样式和脚本无 404

6. 常见坑与解决方法

6.1 Go embed 不支持的文件名

坑点：Go embed 默认不会 embed 以 _ 或 . 开头的文件或目录（详见官方文档）。
表现：Astro 动态路由生成的 _slug_...css 文件不会被 embed，导致页面样式 404。
解决：修改 Vite 构建规则，生成 style-xxx.css 这类文件名。

6.2 macOS 扩展属性影响 embed

坑点：macOS 下某些文件有扩展属性（如 com.apple.provenance），可能导致 embed 失败。
解决：用 xattr -c 文件名 清除扩展属性。

6.3 Docker 构建缓存问题

坑点：修改 embed 语法后，Go 可能用旧缓存，导致 embed 结果不变。
解决：go clean -cache && go clean -modcache，并用 --no-cache 重新 build。

6.4 Go embed 语法必须递归

坑点：//go:embed web/dist/* 只 embed 一级文件，不递归子目录。
解决：必须用 //go:embed web/dist/**。

6.5 生产环境监听地址

坑点：Go 默认监听 127.0.0.1，外部无法访问。
解决：ENV HOST=0.0.0.0，或运行时加 -e HOST=0.0.0.0。

7. 参考资料

8. 总结

前端产物命名规则和Go embed 语法是部署成功的关键
遇到静态资源 404，优先检查 embed 是否包含目标文件
多用 go run 写小测试程序验证 embed 结果
生产环境建议用 Caddy/Nginx 反代实现 HTTPS

如有更多部署细节或自动化脚本需求，欢迎随时补充！