Innei/Shiro 项目 Docker 部署指南

项目概述

Innei/Shiro 是一个基于 Node.js 的 Web 应用项目，采用现代前端技术栈构建。本文将从技术角度详细解析其 Docker 部署方案，帮助开发者理解并实现高效的项目容器化部署。

Dockerfile 架构解析

该 Dockerfile 采用了多阶段构建策略，这是一种优化容器镜像大小的最佳实践，主要分为四个阶段：

1. 基础阶段 (base)：设置 Node.js 环境
2. 依赖阶段 (deps)：安装项目依赖
3. 构建阶段 (builder)：编译项目
4. 运行阶段 (runner)：准备运行环境

详细构建过程

1. 基础阶段配置

FROM node:18-alpine AS base
RUN npm install -g --arch=x64 --platform=linux sharp

• 使用 node:18-alpine 作为基础镜像，Alpine Linux 以轻量著称
• 全局安装 sharp 图像处理库，指定 x64 架构和 Linux 平台

2. 依赖安装阶段

FROM base AS deps
RUN apk add --no-cache libc6-compat
RUN apk add --no-cache python3 make g++
WORKDIR /app
COPY . .
RUN npm install -g pnpm
RUN pnpm install

• 添加必要的系统依赖：libc6-compat、python3、make 和 g++
• 设置工作目录为 /app
• 复制项目所有文件到容器
• 安装 pnpm 包管理器并执行依赖安装

3. 项目构建阶段

FROM base AS builder
RUN apk update && apk add --no-cache git
WORKDIR /app
COPY --from=deps /app/ .
RUN npm install -g pnpm
ENV NODE_ENV production
# 环境变量配置...
RUN pnpm build

• 添加 Git 支持（可能用于构建过程中的版本信息获取）
• 从 deps 阶段复制已安装依赖的项目
• 设置生产环境变量
• 配置多种环境变量（API 密钥、访问密钥等）
• 执行项目构建命令

4. 运行阶段优化

FROM base AS runner
WORKDIR /app
ENV NODE_ENV production
COPY --from=builder /app/public ./public
COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/.next/static ./.next/static
COPY --from=builder /app/.next/server ./.next/server
EXPOSE 2323
ENV PORT 2323
ENV NEXT_SHARP_PATH=/usr/local/lib/node_modules/sharp
CMD echo "Mix Space Web [Shiro] Image." && node server.js

• 仅复制运行所需的文件，最小化镜像体积
• 暴露 2323 端口
• 设置 sharp 库路径环境变量
• 启动命令显示欢迎信息并运行 Node.js 服务

关键环境变量说明

项目构建和运行依赖以下环境变量：

1. API 相关：

   • BASE_URL：基础 API 地址
   • NEXT_PUBLIC_API_URL：公开 API 地址
   • NEXT_PUBLIC_GATEWAY_URL：网关地址

2. 服务集成：

   • S3_ACCESS_KEY 和 S3_SECRET_KEY：S3 存储访问凭证
   • TMDB_API_KEY：电影数据库 API 密钥
   • WEBHOOK_SECRET：Webhook 安全密钥
   • GH_TOKEN：GitHub 访问令牌

部署建议

1. 安全实践：

   • 敏感信息（如 API 密钥）应通过 Docker secrets 或环境变量文件管理
   • 生产环境避免在 Dockerfile 中硬编码敏感信息

2. 性能优化：

   • 考虑使用 Docker 构建缓存加速构建过程
   • 对于 CI/CD 流水线，可以预先构建基础镜像

3. 扩展性考虑：

   • 可根据需要调整 Node.js 内存限制
   • 考虑添加健康检查端点

常见问题解决

1. sharp 库安装问题：

   • 确保架构与平台参数正确匹配
   • Alpine 环境可能需要额外依赖

2. 构建失败：

   • 检查所有必需的环境变量是否已设置
   • 验证网络访问权限（特别是对于私有仓库）

3. 运行时错误：

   • 确认端口未被占用
   • 检查文件权限是否正确

通过本文的详细解析，开发者可以全面理解 Innei/Shiro 项目的 Docker 部署架构，并根据实际需求进行定制化调整。这种多阶段构建方式既保证了构建环境的完整性，又确保了运行环境的最小化，是现代化 Node.js 应用容器化的优秀实践。