| name | docker-build-push |
| description | Podman 镜像构建与推送。包含 Dockerfile 编写、本地构建测试、推送到阿里云 ACR 个人版仓库。当用户需要制作 Dockerfile、打包镜像、推送镜像时使用此技能。 |
Podman 构建与推送
0. 前提条件
检查 Podman 是否已安装
Windows(PowerShell):
podman --version
# 输出示例:podman version 4.9.0
macOS/Linux(终端):
podman --version
如果命令返回版本信息,说明已安装;如果提示 podman : 无法将“podman”项识别为 cmdlet 或 command not found,则需要安装。
安装 Podman
Windows 系统:
winget install RedHat.Podman
macOS 系统:
brew install podman
Linux 系统(以 CentOS/RHEL 为例):
sudo dnf install podman
⚠️ Podman 安装完成后,需要重启终端或重新登录会话使环境变量生效。
1. 推荐基础镜像
| 类型 | 推荐镜像 |
|---|
| Python | crpi-st7s4gabmi4ym1qo.cn-shanghai.personal.cr.aliyuncs.com/rainclaw/python:3.12.13-slim-trixie |
| Node.js | crpi-st7s4gabmi4ym1qo.cn-shanghai.personal.cr.aliyuncs.com/rainclaw/node:22.22.2-trixie-slim |
| Nginx | crpi-st7s4gabmi4ym1qo.cn-shanghai.personal.cr.aliyuncs.com/rainclaw/nginx:stable-alpine |
2. Dockerfile 模板(前后端合一)
一个镜像、一个容器、一个命令,前后端打包在一起。
FROM crpi-st7s4gabmi4ym1qo.cn-shanghai.personal.cr.aliyuncs.com/rainclaw/python:3.12.13-slim-trixie
# 避免中文输出乱码
ENV PYTHONIOENCODING=utf-8
ENV PYTHONUNBUFFERED=1
WORKDIR /app
# 先装依赖(利用缓存层)
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
# 复制后端代码
COPY backend/ ./backend/
# 复制前端文件(原生HTML或打包后的dist)
COPY frontend/dist/ ./dist/
EXPOSE 8000
CMD ["uvicorn", "backend.main:app", "--host", "0.0.0.0", "--port", "8000"]
requirements.txt
fastapi
uvicorn
python-multipart
pandas
openpyxl
根据实际项目删减,pandas/openpyxl 仅 Excel 导入时需要。
3. 前端打包
方式A:原生 HTML/CSS/JS(无框架)
- 直接放到
frontend/ 目录,Dockerfile 里 COPY frontend/ ./frontend/
- 后端用
FileResponse 按上述方式逐个返回
方式B:Vue/React(Vite 打包)
cd frontend && npm install && npm run build
- Dockerfile 里
COPY frontend/dist/ ./dist/
4. 构建与本地测试
# 构建镜像
podman build -t myapp:latest .
# 本地运行测试
podman run -d --name myapp -p 8000:8000 myapp:latest
# 查看日志(确认启动无报错)
podman logs myapp
# 测试 API
curl.exe http://localhost:8000/api/products
# 清理
podman rm -f myapp
5. 推送到阿里云 ACR
5.1 前置:在 ACR 控制台创建仓库
- 打开 ACR 控制台,找到实例地址(如
crpi-xxxxxx.cn-shanghai.personal.cr.aliyuncs.com)
- 命名空间管理 → 创建命名空间(如
web-soft)
- 仓库列表 → 创建仓库 → 填写命名空间 + 仓库名(如
ecommerce-admin)
⚠️ 仓库不会自动创建,推送前必须先在控制台建好,否则报 insufficient_scope。
5.2 登录
阿里云 ACR 登录密码不是阿里云账号密码,是在 ACR 控制台设置的独立访问密码。
podman login --username=<用户名> --password=<密码> <ACR实例地址>
⚠️ PowerShell 中 --password-stdin + echo "xxx" | 不生效,直接用 --password= 参数最简单。
5.3 打标签 + 推送
# 打标签(默认推荐 latest)
podman tag myapp:latest <ACR实例地址>/<命名空间>/<仓库名>:latest
# 推送
podman push <ACR实例地址>/<命名空间>/<仓库名>:latest
💡 生产环境推荐使用语义化版本(如 v1.0.0)替代 latest,便于回滚。
5.4 已知的 ACR 地址
ACR实例地址: crpi-st7s4gabmi4ym1qo.cn-shanghai.personal.cr.aliyuncs.com
命名空间: web-soft
6. ⚠️ 常见错误
错误 1:模块导入路径 ModuleNotFoundError
症状:
ModuleNotFoundError: No module named 'database'
修复: 请参考 simple-web-dev-guide 技能中的"模块导入路径"规范,使用 from backend.xxx import 格式。
错误 2:insufficient_scope: authorization failed
仓库不存在。去 ACR 控制台创建命名空间 + 仓库后再推送。
错误 3:unauthorized: authentication required
用户名或密码错误。ACR 密码是独立访问密码,不是阿里云账号密码。
错误 4:PowerShell && 报错
PowerShell 5.x 不支持 &&。用 pwsh(PowerShell 7+)或分步执行。
错误 5:PowerShell 中文乱码
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
或用 Python 脚本处理,避免直接在终端输出中文。
错误 6:No such image
podman images 确认本地镜像名,用引号包裹含特殊字符的完整路径。
7. 构建与推送检查清单