Skip to content

Magic 入门教程

一、系统要求

  • 支持操作系统:macOS、Linux 或 Windows
  • 已安装 Docker 和 Docker Compose(安装 Docker 参考 3.3)
  • 网络连接(用于拉取镜像和检测公网 IP)
  • 已安装 Git (用于拉取 Magic 代码)

二、安装步骤

2.1 克隆项目

bash
git clone git@github.com:dtyq/magic.git
cd magic

git clone magic

2.2. 配置文件

主要配置文件

  • .env:主要环境变量配置文件
  • config/.env_super_magic:Super Magic 服务配置文件(如果选择安装)
  • config/.env_magic_gateway:Magic Gateway 配置文件(如果选择安装 Super Magic)
  • config/.env_sandbox_gateway:Sandbox Gateway 配置文件(如果选择安装 Super Magic)
  • macOS/Linux 安装过程中,如果不存在文件不存在,会自动复制,Windows 需要手动复制修改
手动配置文件,并修改所需要的值
bash
# 如需要使用 Magic,复制 .env.example 到 .env
sudo cp .env.example .env
Magic 环境变量配置参考:

https://docs.letsmagic.cn/zh/development/deploy/environment.html

bash
# 如需使用 Super Magic 服务,复制以下文件:
sudo cp config/.env_super_magic.example  config/.env_super_magic
sudo cp config/.env_magic_gateway.example  config/.env_magic_gateway
sudo cp config/.env_sandbox_gateway.example  config/.env_sandbox_gateway
Super Magic 环境变量配置参考:

https://docs.letsmagic.cn/zh/development/deploy/super-magic.html

配置 IP(可选)

如果是远程服务器部署,编辑 .env 文件,将以下内容中的 localhost 替换为服务器 IP:

MAGIC_SOCKET_BASE_URL=ws://<服务器IP>:9502
MAGIC_SERVICE_BASE_URL=http://<服务器IP>:9501

如果您选择安装 Super Magic 服务,请确保以下配置文件存在:

  • config/.env_super_magic
  • config/.env_magic_gateway
  • config/.env_sandbox_gateway

如果 config/.env_super_magic 不存在但有 config/.env_super_magic.example,请按照提示复制并编辑该文件。

2.3. macOS/Linux 启动服务

macOS/Linux

运行安装脚本:

bash
sudo ./bin/magic.sh start

Windows

Windows 系统可以不使用 magic.sh 脚本,直接使用 docker compose 命令: 也可以通过下载 Git GUI 工具 获得跟 macOS/Linux 一样的安装体验

bash
# 创建必要的网络
docker network create magic-sandbox-network

# 启动基本服务
docker compose up

如需启动 Super Magic 相关服务:

bash
docker compose --profile magic-gateway --profile sandbox-gateway up

2.4. 安装流程引导

macOS/Linux

脚本将引导您完成以下步骤:

语言选择
  • 选择 1 for English
  • 选择 2 for 中文 语言选择
部署方式选择
  • 选择 1 表示本地电脑部署(使用默认 localhost 配置)

  • 选择 2 表示远程服务器部署(会检测公网 IP 并询问是否使用) 部署方式选择

  • 提示:脚本会判断本地是否已经创建了 magic-sandbox-network,如果没有会自动执行一次:

bash
docker network create magic-sandbox-network
Super Magic 服务安装
  • 选择 1 表示安装 Super Magic 服务(需要提前配置 config/ 目录下的配置文件)
  • 选择 2 表示不安装 Super Magic 服务 Super Magic 服务安装

2.5 首次运行

首次运行后,系统会创建 bin/magic.lock 文件(macOS/Linux),下次启动将跳过安装配置流程。

三、使用方法

3.1 常用命令

macOS/Linux

bash
sudo ./bin/magic.sh [命令]

可用命令:

  • start:在前台启动服务
  • daemon:在后台启动服务
  • stop:停止所有服务
  • restart:重启所有服务
  • status:显示服务状态
  • logs:显示服务日志
  • super-magic:仅启动 Super Magic 服务(前台)
  • super-magic-daemon:仅启动 Super Magic 服务(后台)
  • help:显示帮助信息

Windows

Windows 用户直接使用 docker compose 命令:

bash
# 前台启动服务
docker compose up

# 后台启动服务
docker compose up -d

# 停止服务
docker compose down

# 重启服务
docker compose restart

# 查看服务状态
docker compose ps

# 查看日志
docker compose logs -f

# 使用 Super Magic 服务(前台)
docker compose --profile magic-gateway --profile sandbox-gateway up

# 使用 Super Magic 服务(后台)
docker compose --profile magic-gateway --profile sandbox-gateway up -d

3.2 示例

启动服务

macOS/Linux:

bash
./bin/magic.sh start

Windows:

bash
docker compose up

后台启动服务

macOS/Linux:

bash
./bin/magic.sh daemon

Windows:

bash
docker compose up -d

查看服务状态

macOS/Linux:

bash
./bin/magic.sh status

Windows:

bash
docker compose ps

查看日志

macOS/Linux:

bash
./bin/magic.sh logs

Windows:

bash
docker compose logs -f

3.3 安装 Docker

macOS

  1. 访问 https://docs.docker.com/desktop/install/mac-install/

  2. 下载并安装 Docker Desktop for Mac 下载并安装 Docker Desktop for Mac

  3. 启动 Docker Desktop 应用程序 启动 Docker Desktop 应用程序

Linux

  1. 访问 https://docs.docker.com/engine/install/
  2. 按照您的 Linux 发行版安装说明进行操作,下面使用 Ubuntu 为演示例子:
bash
sudo apt update
# Add Docker's official GPG key:
sudo apt-get update
sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# Add the repository to Apt sources:
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update

bash
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

  1. 安装完成后启动 Docker 服务:
bash
sudo systemctl start docker

Windows

  1. 访问 https://docs.docker.com/desktop/install/windows-install/

  2. 下载并安装 Docker Desktop for Windows 下载并安装 Docker Desktop for Windows

  3. 启动 Docker Desktop 应用程序

  4. 确保在设置中启用了 WSL 2 后端

四、故障排除

常见问题

  1. Docker 未运行

    • 确保 Docker 服务已启动
    • macOS:打开 Docker Desktop 应用
    • Linux:运行 sudo systemctl start docker
    • Windows:打开 Docker Desktop 应用,检查系统托盘图标
  2. 端口冲突

    • 检查是否有其他服务占用了配置中使用的端口
    • 修改 .env 文件中的端口配置
  3. 配置文件缺失

    • 按照提示复制示例配置文件并进行必要的编辑
  4. 网络问题

    • 确保能够访问 Docker Hub 以拉取镜像
    • 检查防火墙设置是否阻止了 Docker 的网络访问
  5. Windows 特有问题

    • 确保开启了 WSL 2 支持
    • 如遇到权限问题,尝试以管理员身份运行命令提示符
    • 检查 Windows 防火墙是否阻止了 Docker 网络流量
  6. 日志查看

    • super-magic 查看 sandbox-agent 开头的容器日志
    • 接口问题查看 magic-service 容器日志
    • 前端 UI 问题查看 magic-web 容器日志
    • 跨域等网络问题查看 magic-caddy 容器日志

五、卸载

如需卸载 Magic 系统:

  1. 停止并移除所有容器

    macOS/Linux:

    bash
    ./bin/magic.sh stop

    Windows:

    bash
    docker compose down
  2. 移除 Docker 网络(如有需要)

    bash
    docker network rm magic-sandbox-network
  3. 删除持久化文件目录 ./volumes

基于 Apache 2.0 许可发布