Docker 部署

本指南介绍如何使用 Docker 容器化部署 TinyShip 项目的 Next.js 和 Nuxt.js 应用。

前置条件

Docker >= 20.10
Docker Compose >= 2.0

推荐方式：Docker Compose

使用项目根目录的 docker-compose.yml 文件，可以分别启动 Next.js 或 Nuxt.js 应用：

# 启动 Next.js 应用
docker compose --profile next up -d

# 启动 Nuxt.js 应用  
docker compose --profile nuxt up -d

# 查看日志
docker compose logs -f

# 停止应用
docker compose down

手动 Docker 部署

Next.js 部署

# 1. 确保项目根目录有 .env 文件，然后构建镜像
docker build -t tinyship-next -f apps/next-app/Dockerfile .

# 2. 运行容器
docker run -d \
  --name tinyship-next \
  -p 7001:7001 \
  --env-file .env \
  --restart unless-stopped \
  tinyship-next

Nuxt.js 部署

# 1. 确保项目根目录有 .env 文件，然后构建镜像
docker build -t tinyship-nuxt -f apps/nuxt-app/Dockerfile .

# 2. 运行容器
docker run -d \
  --name tinyship-nuxt \
  -p 7001:7001 \
  --env-file .env \
  --restart unless-stopped \
  tinyship-nuxt

重要提醒

构建路径

必须在项目根目录运行 docker build 命令
使用 -f 参数指定 Dockerfile 路径
构建上下文是项目根目录 (.)

跨平台构建

如果你在不同架构的机器间部署（如 M1/M2 Mac 构建，AMD64 服务器运行）：

# 为特定平台构建
docker build --platform linux/amd64 -t tinyship-next -f apps/next-app/Dockerfile .

# 或者构建多平台镜像
docker buildx build --platform linux/amd64,linux/arm64 -t tinyship-next -f apps/next-app/Dockerfile .

平台对应关系：

平台	架构
M1/M2 Mac	`linux/arm64`
Intel Mac/Windows/Linux	`linux/amd64`
大部分云服务器	`linux/amd64`

构建依赖

Dockerfile 会自动复制这些必要的配置文件：

turbo.json - Turbo 构建配置
config.ts - 应用配置文件
tsconfig.json - TypeScript 路径别名
libs/ - 共享库目录

构建时环境变量

支持两种构建模式，自动适配不同环境：

本地开发构建

Dockerfile 会自动复制项目根目录的 .env 文件 (如果存在)
前端公开变量自动读取：NEXT_PUBLIC_TURNSTILE_SITE_KEY、NEXT_PUBLIC_WECHAT_APP_ID
无需任何额外参数，一行命令构建

CI/CD 环境构建

支持通过 --build-arg 传入环境变量
GitHub Actions/其他 CI 环境中没有 .env 文件也能正常构建
优先级：构建参数 > .env 文件 > 默认值

数据库连接配置

Docker 容器中不能使用 localhost 连接宿主机服务：

# 错误 - 容器内访问不到宿主机的 localhost
DATABASE_URL=postgresql://localhost:5432/db

# Mac/Windows Docker Desktop:
DATABASE_URL=postgresql://viking@host.docker.internal:5432/tinyship_dev

# Linux VPS 网桥模式:
DATABASE_URL=postgresql://viking@172.17.0.1:5432/tinyship_dev

# Linux VPS 主机网络模式 (推荐):
DATABASE_URL=postgresql://viking@localhost:5432/tinyship_dev

Linux VPS 主机网络模式：

docker run -d \
  --name tinyship-nuxt \
  --network host \
  --env-file .env \
  --restart unless-stopped \
  tinyship-nuxt

Docker Compose 详细说明

使用命令

# 启动 Next.js 应用
docker compose --profile next up -d

# 启动 Nuxt.js 应用
docker compose --profile nuxt up -d

# 重新构建并启动
docker compose --profile next up -d --build

# 查看日志
docker compose logs -f

# 停止应用
docker compose down

# 查看运行状态
docker compose ps

重启策略

--restart unless-stopped 参数含义：

容器崩溃时：自动重启
Docker 服务重启时：自动重启容器
服务器重启时：自动重启容器
手动停止时：不会重启（docker stop）

环境变量示例

创建 .env 文件用于 Docker 部署：

.env

NODE_ENV=production

# 数据库连接 - 根据运行方式选择
# Mac/Windows Docker Desktop:
# DATABASE_URL=postgresql://viking@host.docker.internal:5432/tinyship_dev
# Linux VPS 主机网络模式 (推荐):
DATABASE_URL=postgresql://viking@localhost:5432/tinyship_dev

# 应用 URL - 保持实际访问地址
APP_BASE_URL=https://yourdomain.com
BETTER_AUTH_SECRET=your-production-secret-key
BETTER_AUTH_URL=https://yourdomain.com

常用命令

# 查看运行中的容器
docker ps

# 查看日志
docker logs tinyship-next
docker logs tinyship-nuxt

# 停止容器
docker stop tinyship-next

# 删除容器
docker rm tinyship-next

# 删除镜像
docker rmi tinyship-next

# 进入容器调试
docker exec -it tinyship-next /bin/sh

# 查看容器资源使用
docker stats

# 清理无用的镜像和容器
docker system prune

故障排除

常见问题

问题	解决方案
构建失败 - lockfile 不兼容	检查 pnpm 版本，更新 Dockerfile 中的 pnpm 版本
找不到 turbo.json	确保在项目根目录运行 docker build 命令
数据库连接失败	检查 `host.docker.internal` 配置和用户名
端口已被占用	修改端口映射或停止占用端口的服务
环境变量未生效	检查 `.env` 文件路径和格式
平台架构不匹配	使用 `--platform` 参数指定目标平台构建

日志调试

# 查看构建过程日志
docker build -t tinyship-next -f apps/next-app/Dockerfile . --no-cache

# 检查镜像平台架构
docker image inspect tinyship-next --format='{{.Architecture}}'

# 查看容器启动日志
docker logs tinyship-next --follow

# 查看 Docker Compose 日志
docker compose logs -f --tail=100

性能优化

# 设置资源限制
docker run -d \
  --name tinyship-next \
  --memory=1g \
  --cpus=0.5 \
  -p 7001:7001 \
  tinyship-next

返回部署概览

本指南介绍如何使用 Docker 容器化部署 TinyShip 项目的 Next.js 和 Nuxt.js 应用。

前置条件

Docker >= 20.10
Docker Compose >= 2.0

推荐方式：Docker Compose

使用项目根目录的 docker-compose.yml 文件，可以分别启动 Next.js 或 Nuxt.js 应用：

# 启动 Next.js 应用
docker compose --profile next up -d

# 启动 Nuxt.js 应用  
docker compose --profile nuxt up -d

# 查看日志
docker compose logs -f

# 停止应用
docker compose down

手动 Docker 部署

Next.js 部署

# 1. 确保项目根目录有 .env 文件，然后构建镜像
docker build -t tinyship-next -f apps/next-app/Dockerfile .

# 2. 运行容器
docker run -d \
  --name tinyship-next \
  -p 7001:7001 \
  --env-file .env \
  --restart unless-stopped \
  tinyship-next

Nuxt.js 部署

# 1. 确保项目根目录有 .env 文件，然后构建镜像
docker build -t tinyship-nuxt -f apps/nuxt-app/Dockerfile .

# 2. 运行容器
docker run -d \
  --name tinyship-nuxt \
  -p 7001:7001 \
  --env-file .env \
  --restart unless-stopped \
  tinyship-nuxt

重要提醒

构建路径

必须在项目根目录运行 docker build 命令
使用 -f 参数指定 Dockerfile 路径
构建上下文是项目根目录 (.)

跨平台构建

如果你在不同架构的机器间部署（如 M1/M2 Mac 构建，AMD64 服务器运行）：

# 为特定平台构建
docker build --platform linux/amd64 -t tinyship-next -f apps/next-app/Dockerfile .

# 或者构建多平台镜像
docker buildx build --platform linux/amd64,linux/arm64 -t tinyship-next -f apps/next-app/Dockerfile .

平台对应关系：

平台	架构
M1/M2 Mac	`linux/arm64`
Intel Mac/Windows/Linux	`linux/amd64`
大部分云服务器	`linux/amd64`

构建依赖

Dockerfile 会自动复制这些必要的配置文件：

turbo.json - Turbo 构建配置
config.ts - 应用配置文件
tsconfig.json - TypeScript 路径别名
libs/ - 共享库目录

构建时环境变量

支持两种构建模式，自动适配不同环境：

本地开发构建

Dockerfile 会自动复制项目根目录的 .env 文件 (如果存在)
前端公开变量自动读取：NEXT_PUBLIC_TURNSTILE_SITE_KEY、NEXT_PUBLIC_WECHAT_APP_ID
无需任何额外参数，一行命令构建

CI/CD 环境构建

支持通过 --build-arg 传入环境变量
GitHub Actions/其他 CI 环境中没有 .env 文件也能正常构建
优先级：构建参数 > .env 文件 > 默认值

数据库连接配置

Docker 容器中不能使用 localhost 连接宿主机服务：

# 错误 - 容器内访问不到宿主机的 localhost
DATABASE_URL=postgresql://localhost:5432/db

# Mac/Windows Docker Desktop:
DATABASE_URL=postgresql://viking@host.docker.internal:5432/tinyship_dev

# Linux VPS 网桥模式:
DATABASE_URL=postgresql://viking@172.17.0.1:5432/tinyship_dev

# Linux VPS 主机网络模式 (推荐):
DATABASE_URL=postgresql://viking@localhost:5432/tinyship_dev

Linux VPS 主机网络模式：

docker run -d \
  --name tinyship-nuxt \
  --network host \
  --env-file .env \
  --restart unless-stopped \
  tinyship-nuxt

Docker Compose 详细说明

使用命令

# 启动 Next.js 应用
docker compose --profile next up -d

# 启动 Nuxt.js 应用
docker compose --profile nuxt up -d

# 重新构建并启动
docker compose --profile next up -d --build

# 查看日志
docker compose logs -f

# 停止应用
docker compose down

# 查看运行状态
docker compose ps

重启策略

--restart unless-stopped 参数含义：

容器崩溃时：自动重启
Docker 服务重启时：自动重启容器
服务器重启时：自动重启容器
手动停止时：不会重启（docker stop）

环境变量示例

创建 .env 文件用于 Docker 部署：

.env

NODE_ENV=production

# 数据库连接 - 根据运行方式选择
# Mac/Windows Docker Desktop:
# DATABASE_URL=postgresql://viking@host.docker.internal:5432/tinyship_dev
# Linux VPS 主机网络模式 (推荐):
DATABASE_URL=postgresql://viking@localhost:5432/tinyship_dev

# 应用 URL - 保持实际访问地址
APP_BASE_URL=https://yourdomain.com
BETTER_AUTH_SECRET=your-production-secret-key
BETTER_AUTH_URL=https://yourdomain.com

常用命令

# 查看运行中的容器
docker ps

# 查看日志
docker logs tinyship-next
docker logs tinyship-nuxt

# 停止容器
docker stop tinyship-next

# 删除容器
docker rm tinyship-next

# 删除镜像
docker rmi tinyship-next

# 进入容器调试
docker exec -it tinyship-next /bin/sh

# 查看容器资源使用
docker stats

# 清理无用的镜像和容器
docker system prune

故障排除

常见问题

问题	解决方案
构建失败 - lockfile 不兼容	检查 pnpm 版本，更新 Dockerfile 中的 pnpm 版本
找不到 turbo.json	确保在项目根目录运行 docker build 命令
数据库连接失败	检查 `host.docker.internal` 配置和用户名
端口已被占用	修改端口映射或停止占用端口的服务
环境变量未生效	检查 `.env` 文件路径和格式
平台架构不匹配	使用 `--platform` 参数指定目标平台构建

日志调试

# 查看构建过程日志
docker build -t tinyship-next -f apps/next-app/Dockerfile . --no-cache

# 检查镜像平台架构
docker image inspect tinyship-next --format='{{.Architecture}}'

# 查看容器启动日志
docker logs tinyship-next --follow

# 查看 Docker Compose 日志
docker compose logs -f --tail=100

性能优化

# 设置资源限制
docker run -d \
  --name tinyship-next \
  --memory=1g \
  --cpus=0.5 \
  -p 7001:7001 \
  tinyship-next

返回部署概览

Docker 部署

On this page

Docker 部署

On this page