基于 MAC-RUNGUIDE 的完整启动流程

一、venv

Python 虚拟环境模块

‌venv 是 Python 内置的虚拟环境模块‌，全称为 Virtual Environment，用于创建独立的 Python 运行空间。根据 Python 官方文档及海外权威技术站点介绍，它允许开发者为不同项目配置隔离的环境，避免依赖包版本冲突。‌‌

‌核心作用‌：隔离项目依赖，每个环境拥有独立的 Python 解释器、pip 工具和第三方库目录，互不干扰。

‌基本使用‌：通过命令 python -m venv <环境名> 创建环境，运行激活脚本（如 source <环境名>/bin/activate）后进入该环境。

‌优势‌：无需安装第三方工具，Python 3.3+ 版本默认自带，轻量且标准。‌‌

二、Docker

Docker是一组平台即服务（PaaS）的产品。它基于操作系统层级的虚拟化技术，将软件与其依赖项打包为容器。托管容器的软件称为Docker引擎。Docker能够帮助开发者在轻量级容器中自动部署应用程序，并使得不同容器中的应用程序彼此隔离，高效工作。

Docker是一个开源的平台，用于开发、交付和运行应用程序。它能够在Windows，macOS，Linux计算机上运行，并将某一应用程序及其依赖项打包至一个容器中，这些容器可以在任何支持Docker的环境中运行。容器彼此隔离，但可以通过特定的通道相互传递信息。

Docker提供了一个轻量级的虚拟化解决方案。由于运行在同一计算机上的所有容器共享同一个操作系统内核，避免了启动与维护虚拟机的开销。因此相比于传统的虚拟机，Docker容器更加轻便、快速、容易部署。使用Docker，开发者可以避免在两台计算机上运行效果不一致的问题，容器提供了一致的行为，进而使得应用程序在不同环境的计算机上有相同的运行效果。

前置准备（重点，别跳过）runguide

安装 Docker Desktop：去官网下最新版，安装后启动它。
Apple Silicon Mac 必须开启 Rosetta：
- Docker Desktop → Settings（齿轮图标）→ General → 勾选 Use Rosetta for x86_64/amd64 emulation。
确保磁盘空间充足：这个镜像解压后可能占几十 GB，先确认 Mac 空间够。

第一步：导入镜像（约 10-20 分钟）

打开终端，进入存放这三个文件的目录：

复制代码

cd ~/Downloads  # 替换成你实际放这三个文件的目录
docker load -i jiangxi-cpu-20260910-ui.tar.gz

等待它解压导入，看到类似 Loaded image: geoview-jiangxi:cpu-20260910-ui 就成功了。

2. 确认 Rosetta 已开启（关键！）

Apple Silicon 跑 linux/amd64 镜像必须开 Rosetta ，否则 --platform linux/amd64 会失败或极慢。

打开 Docker Desktop
右上角 齿轮 Settings → General
勾选 "Use Rosetta for x86_64/amd64 emulation on Apple Silicon"
点 Apply & Restart

3. 重新导入镜像

复制代码

cd /Users/like/Desktop/handoff-20260910
docker load -i jiangxi-cpu-20260910-ui.tar.gz

这次应该能顺利走完（10-20 分钟），看到：

复制代码

Loaded image: geoview-jiangxi:cpu-20260910-ui

4. 启动容器

复制代码

docker run -d --name jiangxi-cpu \
  --platform linux/amd64 \
  --env-file jx_env_cpu_20260910.env \
  -p 127.0.0.1:4173:4000 -p 127.0.0.1:4174:3000 -p 127.0.0.1:5178:5008 \
  geoview-jiangxi:cpu-20260910-ui