Nhost CLI Docker镜像文档

镜像概述

Nhost CLI Docker镜像是Nhost后端即服务（Backend as a Service）平台的官方命令行工具容器化版本，旨在简化Nhost项目的本地开发、配置管理和云部署流程。Nhost平台提供集成的后端服务，包括PostgreSQL数据库、身份验证系统、对象存储和无服务器函数，该镜像通过容器化方式确保开发环境一致性和跨平台兼容性。

核心功能和特性

• 本地开发环境模拟：在本地精确复制Nhost云服务配置，包括数据库、身份验证和存储服务，实现"本地开发-云部署"无缝衔接
• 项目生命周期管理：支持项目初始化、配置更新、版本控制和部署流程全链路管理
• 数据库工具集成：内置PostgreSQL客户端，支持数据库迁移、备份、查询和模式管理
• 身份验证配置：可视化管理用户认证策略、角色权限、社交登录集成和JWT配置
• 云服务联动：与Nhost云平台实时同步项目配置，支持多环境（开发/测试/生产）部署管理
• 跨平台一致性：通过Docker容器消除操作系统差异，确保团队成员和CI/CD环境使用统一工具版本

使用场景和适用范围

• 本地开发工作流：开发者在本地构建和测试Nhost后端服务，无需手动配置复杂的基础设施
• CI/CD自动化：集成到持续集成/部署流程，实现项目自动测试、构建和云部署
• 多环境管理：为开发、测试和生产环境维护独立配置，简化环境切换和版本控制
• 团队协作：统一开发工具链，避免"本地环境不一致"导致的协作问题

使用方法和配置说明

基础运行命令

通过Docker命令直接运行Nhost CLI，执行项目管理操作：

docker run --rm -it \
  -v $(pwd):/app \
  -e NHOST_TOKEN=<your-nhost-token> \
  nhost/cli <command>

参数说明：

• --rm：容器退出后自动清理
• -it：启用交互式终端，支持命令行输入
• -v $(pwd):/app：挂载本地项目目录到容器内工作区（/app）
• -e NHOST_TOKEN：设置Nhost认证令牌（从Nhost控制台获取）
• <command>：Nhost CLI命令（如init/dev/deploy）

常用操作示例

1. 初始化新项目

创建并初始化Nhost项目目录：

docker run --rm -it \
  -v $(pwd):/app \
  -e NHOST_TOKEN=<your-nhost-token> \
  nhost/cli init my-nhost-project

2. 启动本地开发服务器

在本地运行Nhost开发环境，映射服务端口到主机：

docker run --rm -it \
  -v $(pwd)/my-nhost-project:/app \
  -p 1337:1337 \  # 后端API端口
  -p 5432:5432 \  # PostgreSQL数据库端口
  -e NHOST_TOKEN=<your-nhost-token> \
  nhost/cli dev

服务启动后，可通过http://localhost:1337访问本地后端API，localhost:5432连接PostgreSQL数据库。

3. 部署项目到Nhost云

将本地项目部署到Nhost云平台指定环境：

docker run --rm -it \
  -v $(pwd)/my-nhost-project:/app \
  -e NHOST_TOKEN=<your-nhost-token> \
  nhost/cli deploy \
  --project <project-id> \
  --region eu-central-1 \
  --environment production

环境变量配置

Docker Compose配置

创建docker-compose.yml简化多参数运行：

version: '3.8'
services:
  nhost-cli:
    image: nhost/cli:latest
    volumes:
      - ./my-nhost-project:/app
      - ~/.nhost:/root/.nhost  # 持久化CLI配置和缓存
    environment:
      - NHOST_TOKEN=${NHOST_TOKEN}
      - NHOST_PROJECT_ID=proj_abc123
      - NHOST_REGION=eu-central-1
    ports:
      - "1337:1337"   # API服务端口
      - "5432:5432"   # PostgreSQL端口
      - "8080:8080"   # 无服务器函数端口
    tty: true
    stdin_open: true

通过以下命令启动开发环境：

export NHOST_TOKEN=<your-token>
docker-compose run --rm nhost-cli dev

版本管理

指定特定版本的Nhost CLI：

docker run --rm nhost/cli:1.28.0 --version  # 查看版本信息

版本标签遵循语义化版本规范，可在Nhost CLI GitHub仓库查看所有可用版本。

注意事项

• 文件权限：确保本地项目目录具有足够权限（推荐设置755权限），避免容器内读写失败
• 数据持久化：本地开发时数据库数据默认存储在容器内，如需持久化，可额外挂载PostgreSQL数据卷：

  -v nhost-pgdata:/var/lib/postgresql/data
  

• 网络配置：如需让其他容器访问Nhost服务，可通过Docker网络别名实现服务发现
• 令牌安全：避免将NHOST_TOKEN硬编码到脚本，建议通过环境变量或 secrets 管理工具注入