Beego项目容器化必须编译为静态二进制再运行，禁用bee run；因bee run依赖Go环境、源码及硬编码路径，无法在生产镜像中运行，正确做法是多阶段构建：golang:alpine编译（CGO_ENABLED=0），scratch运行，COPY conf/static/views并确保路径、权限、编码（UTF-8无BOM）正确。
Beego 项目做容器镜像，核心就一条：别用 bee run，必须编译成二进制再运行。 否则镜像体积大、启动慢、时区/权限/配置加载全出问题。
为什么不能直接 COPY 源码 + bee run？
Beego 的 bee run 是开发模式热重载工具，依赖 Go 编译环境、源码、conf/app.conf 路径硬编码、甚至临时生成的路由文件。它在容器里根本跑不起来——bee 工具默认不进生产镜像，go 环境也不该出现在 alpine 镜像里。
- 常见错误现象：
command not found: bee、panic: open conf/app.conf: no such file or directory、fork/exec /bin/sh: no such file or directory（alpine 缺/bin/sh） - 真实使用场景：生产部署只运行编译好的可执行文件，
bee仅用于本地开发 - 正确路径：Go 编译 → 静态二进制 → COPY 到轻量基础镜像（如
golang:alpine或scratch）→ 启动二进制
Dockerfile 必须包含的三步关键操作
一个最小可行的 Beego 镜像构建流程，重点在分离构建阶段和运行阶段：
- 第一阶段用
golang:alpine编译：确保CGO_ENABLED=0，否则二进制会动态链接 libc，无法在scratch运行 - COPY 配置和静态资源：Beego 默认读
conf/app.conf和static/、views/，这些必须在运行时存在，且路径要和代码里beego.BConfig.WebConfig.StaticDir一致 - 第二阶段用
scratch或alpine：推荐scratch（零依赖），但得提前确认 Beego 没调用外部命令（如exec.Command("sh")）；若用了，改用alpine:latest并apk add --no-cache ca-certificates
示例关键片段：
FROM golang:alpine AS builder WORKDIR /app COPY go.mod go.sum ./ RUN go mod download COPY . . RUN CGO_ENABLED=0 GOOS=linux go build -a -installsuffix cgo -o mindoc . <p>FROM scratch COPY --from=builder /app/mindoc /mindoc COPY --from=builder /app/conf /conf COPY --from=builder /app/static /static COPY --from=builder /app/views /views EXPOSE 8181 CMD ["/mindoc"]</p>
docker-compose.yml 中容易漏掉的环境与挂载
Beego 应用在容器里常因配置路径或外部依赖失败，docker-compose.yml 必须显式处理以下几项：
-
environment：Beego 通过os.Getenv()读取配置（如数据库地址），不能只靠conf/app.conf；例如 MinDoc 要求MINDOC_DB_HOST、MINDOC_UPLOAD_PATH -
volumes：上传目录（如uploads/）必须挂载宿主机路径，否则重启容器后文档丢失；注意权限 —— alpine 默认以 root 运行，但 Beego 进程常以非 root 用户启动，需提前chown -R 65534:65534 uploads/（65534 是 nobody 用户 UID） -
ports映射要匹配conf/app.conf里的HttpPort，否则访问 8080 却监听 8181，连接被拒
典型写法：
services:
mindoc:
build: .
ports:
- "8181:8181"
environment:
- MINDOC_DB_HOST=mysql
- MINDOC_DB_NAME=mindoc
- MINDOC_UPLOAD_PATH=/data/uploads
volumes:
- ./uploads:/data/uploads
- ./conf/app.conf:/conf/app.conf
启动后 502 / 404 / 静态资源 403 的快速排查点
容器跑起来了但打不开页面，八成是 Beego 的路径或权限没对齐：
-
404：检查conf/app.conf中AppPath是否指向正确工作目录（应为/或.），Beego 会据此拼接views/和static/路径 -
403 Forbiddenon/static/xxx.css：确认StaticDir配置值（如static）与实际挂载到容器内的路径一致，且文件有可读权限（chmod -R a+r static/） -
502 Bad Gateway（Nginx 前置时）：不是 Beego 错，而是容器没真正监听成功 —— 进容器执行netstat -tlnp，看:8181是否被你的二进制进程绑定；常见原因是app.conf里RunMode = dev导致监听127.0.0.1:8181而非0.0.0.0:8181
最易被忽略的是：Beego 的 conf/app.conf 在容器内必须是 UTF-8 编码且无 BOM，Windows 编辑保存的文件极大概率导致启动静默失败 —— 用 file -i app.conf 检查编码，用 dos2unix 清理换行符。
