第2章环境准备与快速上手

作者

谭策 — 独立开发者 | AIOps 领域探索者

🌐 项目官网：ITOpsAgentinfo
📝 博客：zjzwfw.cloud
📧 邮箱：huawei_network@foxmail.com
💬 微信公众号：IT Online

IT Online 微信公众号

许可证

MPL-2.0 © 谭策

本章导读

本章学习目标

完成本章学习后，你将能够：

✅ 在你的电脑上安装所有必需的软件
✅ 从 GitHub 克隆项目代码
✅ 使用一键脚本启动项目
✅ 使用 Docker Compose 部署项目
✅ 使用本地开发模式（热重载）
✅ 验证服务是否正常启动
✅ 解决常见的环境配置问题

前置知识要求

✅ 第1章内容（了解项目是什么）
✅ 会使用电脑的文件管理器
✅ 会使用命令行（会 cd、ls 等基本命令）

💡 零基础提示：如果你没有命令行经验，不用担心！本章的每个命令都有详细说明，照着复制粘贴就行。

预计学习时间

45-60 分钟

2.1 环境要求

在开始之前，我们需要确保电脑上有以下软件。别担心，每个软件我都会告诉你怎么安装。

2.1.1 必需软件

软件	最低版本	推荐版本	用途	是否必须
Node.js	18.0.0	20.x LTS	运行后端代码	✅ 必须
npm 或 pnpm	npm 9+	pnpm 8+	安装依赖包	✅ 必须
Git	2.0+	最新版	下载项目代码	✅ 必须
Docker	20.0+	最新版	容器化部署	✅ 必须

2.1.2 可选软件

软件	用途	推荐程度
VS Code	代码编辑器	⭐⭐⭐⭐⭐ 强烈推荐
Docker Desktop	Docker 图形界面	⭐⭐⭐⭐ Windows/Mac 推荐
GitHub Desktop	Git 图形界面	⭐⭐⭐ 新手友好
Terminal / PowerShell	命令行工具	⭐⭐⭐ 系统自带即可

2.2 安装必需软件

2.2.1 安装 Node.js

Node.js 是什么？ Node.js 是一个让 JavaScript 能在服务器上运行的软件。你可以把它理解为"JavaScript 的运行引擎"。就像视频需要播放器才能播放一样，我们的后端代码需要 Node.js 才能运行。

Windows 安装步骤：

打开浏览器，访问 https://nodejs.org/
你会看到一个页面，有两个绿色按钮。点击左边的 LTS（长期支持版）按钮下载
下载完成后，双击 .msi 安装文件
一直点击 Next（下一步），使用默认设置即可
最后点击 Install 安装
安装完成后，点击 Finish

Mac 安装步骤：

打开浏览器，访问 https://nodejs.org/
点击 LTS 按钮下载 .pkg 文件
双击下载的 .pkg 文件
按提示完成安装

Linux (Ubuntu) 安装步骤：

bash

# 添加 NodeSource 仓库（获取最新 LTS 版本）
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -

# 安装 Node.js（会自动包含 npm）
sudo apt-get install -y nodejs

# 验证安装
node --version
npm --version

验证安装是否成功：

打开命令行工具（Windows 是 CMD 或 PowerShell，Mac/Linux 是 Terminal），输入以下命令：

bash

# 检查 Node.js 版本
node --version
# 应该显示类似: v20.11.0

# 检查 npm 版本
npm --version
# 应该显示类似: 10.2.4

⚠️ 注意：如果显示 command not found 或 不是内部或外部命令，说明安装没有成功。请重新安装，并确保安装后重新打开了命令行窗口。

2.2.2 安装 Git

Git 是什么？ Git 是一个版本管理工具，用来管理和追踪代码的变化。你可以把它理解为"代码的存档工具"，它让我们能方便地下载项目代码。

Windows 安装步骤：

访问 https://git-scm.com/download/win
点击 Click here to download 自动下载
双击下载的安装文件
一直点击 Next，使用默认设置
最后点击 Install 安装

Mac 安装步骤：

bash

# 方法一：使用 Homebrew（推荐）
brew install git

# 方法二：Xcode 命令行工具
xcode-select --install

Linux (Ubuntu) 安装步骤：

bash

sudo apt-get update
sudo apt-get install -y git

验证安装：

bash

git --version
# 应该显示类似: git version 2.43.0

2.2.3 安装 Docker

Docker 是什么？ Docker 是一个"容器化"工具。你可以把它理解为"快递包装盒"——它把我们的应用和所有需要的东西（Node.js、数据库、配置文件等）打包在一起，这样在任何电脑上都能运行，不用担心"在我电脑上能跑，在别的地方不行"的问题。

Windows 安装步骤：

访问 https://www.docker.com/products/docker-desktop/
点击 Download Docker Desktop
选择 Windows 版本下载
双击下载的安装文件
安装完成后，重启电脑（这一步很重要！）
打开 Docker Desktop，同意服务条款
等待 Docker 启动完成（右下角托盘图标变成绿色）

⚠️ Windows 重要提示：Docker Desktop 需要 Windows 10/11 专业版或企业版才能正常运行。如果你是家庭版，可能需要启用 WSL2（Windows Subsystem for Linux）。如果安装遇到问题，请参考 Docker 官方文档。

Mac 安装步骤：

访问 https://www.docker.com/products/docker-desktop/
点击 Download Docker Desktop
选择 Mac 版本（Intel 或 Apple Silicon）下载
将 .dmg 中的 Docker 拖到 Applications 文件夹
打开 Docker Desktop，同意服务条款
等待 Docker 启动完成

Linux (Ubuntu) 安装步骤：

bash

# 使用官方一键安装脚本
curl -fsSL https://get.docker.com | sh

# 添加当前用户到 docker 组（避免每次用 sudo）
sudo usermod -aG docker $USER

# 需要注销并重新登录才能生效

验证安装：

bash

docker --version
# 应该显示类似: Docker version 24.0.7

docker-compose --version
# 应该显示类似: Docker Compose version v2.23.0

# 测试运行一个容器
docker run hello-world
# 应该看到 "Hello from Docker!" 的欢迎信息

2.2.4 安装 VS Code（强烈推荐）

VS Code 是什么？ VS Code（Visual Studio Code）是微软开发的免费代码编辑器。它不仅支持代码编辑，还有丰富的插件生态系统。

安装步骤：

访问 https://code.visualstudio.com/
点击下载按钮（会自动识别你的操作系统）
下载完成后安装
打开 VS Code

推荐安装的插件：

在 VS Code 中，点击左侧的扩展图标（四个方块的图标），搜索并安装以下插件：

插件名	用途
ESLint	代码规范检查
Prettier	代码格式化
TypeScript 官方扩展	TypeScript 支持
Tailwind CSS IntelliSense	Tailwind 样式提示
ES7+ React/Redux Snippets	React 代码片段
GitLens	Git 增强
REST Client	API 测试

2.3 获取项目代码

方式一：使用 Git 克隆（推荐）

这是最常用的方式，以后更新代码也最方便。

步骤：

打开命令行工具
进入你想存放项目的文件夹（比如桌面）

bash

# Windows - 进入桌面
cd Desktop

# Mac/Linux
cd ~/Desktop

克隆项目代码

bash

git clone https://github.com/qinshihu/itops-agent-platform.git

bash

cd itops-agent-platform

查看项目结构

bash

# Windows
dir

# Mac/Linux
ls

你应该能看到类似这样的文件列表：

📁 itops-agent-platform/
 ├── 📁 backend/           ← 后端代码
 ├── 📁 frontend/          ← 前端代码
 ├── 📁 docker/            ← Docker 配置
 ├── 📁 docs/              ← 文档
 ├── 📁 .github/           ← CI/CD 配置
 ├── docker-compose.yml    ← Docker 编排文件
 ├── .env.example          ← 环境变量示例
 ├── README.md             ← 项目说明
 └── deploy.ps1            ← 一键部署脚本

方式二：下载 ZIP 压缩包

如果你不想安装 Git，也可以直接从 GitHub 下载。

访问 https://github.com/qinshihu/itops-agent-platform
点击绿色的 Code 按钮
点击 Download ZIP
解压到你想存放的位置
进入解压后的文件夹

⚠️ 注意：使用 ZIP 方式下载后，以后更新代码需要重新下载。所以推荐还是使用 Git 方式。

2.4 部署方式选择

项目提供了三种启动方式，你可以根据自己的需求选择：

┌──────────────────────────────────────────────────────────┐
│                  三种部署方式对比                           │
│                                                          │
│  方式一：一键脚本部署 🚀                                   │
│  适合人群：想快速体验，不需要修改代码                      │
│  优点：最简单，5 分钟搞定                                  │
│  缺点：代码更新需要重新拉取                                │
│                                                          │
│  方式二：Docker Compose 部署 🐳                           │
│  适合人群：想自己控制部署细节                              │
│  优点：可自定义配置，适合生产环境                          │
│  缺点：需要手动配置环境变量                                │
│                                                          │
│  方式三：本地开发模式 💻                                   │
│  适合人群：需要修改代码、二次开发                          │
│  优点：热重载，改代码即时看到效果                         │
│  缺点：需要安装更多依赖，配置稍复杂                        │
│                                                          │
└──────────────────────────────────────────────────────────┘

我的建议：

第一次接触项目 → 选择 方式一（一键脚本）
想部署到生产环境 → 选择 方式二（Docker Compose）
想修改代码学习 → 选择 方式三（本地开发模式）

2.5 方式一：一键脚本部署（推荐新手）

这是最简单的启动方式，只需要运行一个脚本！

Windows 用户

步骤：

打开 PowerShell（在项目目录下）
如果首次运行 PowerShell 脚本，需要修改执行策略：

powershell

# 以管理员身份运行 PowerShell，然后执行：
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

运行部署脚本

powershell

.\deploy.ps1

等待脚本执行完成（大约 2-5 分钟）

脚本会自动完成：

✅ 检查 Docker 是否安装
✅ 从阿里云拉取最新镜像
✅ 生成 .env 配置文件
✅ 启动所有服务
✅ 验证服务健康状态

Linux/Mac 用户

bash

# 添加执行权限
chmod +x deploy.sh

# 运行部署脚本
./deploy.sh

验证部署成功

脚本执行完成后，打开浏览器访问：

前端: http://localhost:8080
后端: http://localhost:3001/health

如果你看到登录页面，说明部署成功了！🎉

2.6 方式二：Docker Compose 部署

这种方式让你更清楚地了解部署的每一步。

步骤 1：配置环境变量

项目使用 .env 文件来管理配置。我们需要从示例文件复制一份并修改。

bash

# 复制示例文件
cp .env.example .env

Windows PowerShell：

powershell

Copy-Item .env.example .env

步骤 2：编辑 .env 文件

打开 .env 文件，至少修改以下配置：

env

# 运行环境
NODE_ENV=production

# 后端端口（一般不用改）
PORT=3001

# JWT 密钥（生产环境必须修改为随机字符串）
JWT_SECRET=my-super-secret-key-change-this-in-production

# CORS 允许的域名（根据实际访问域名修改）
ALLOWED_ORIGINS=http://localhost:8080

# AI API 密钥（至少配置一个，否则 AI 功能无法使用）
DOUBAO_API_KEY=你的豆包API密钥
# 或者
OPENAI_API_KEY=你的OpenAI密钥

🔑 关于 API 密钥：
如果你在中国，推荐使用火山引擎豆包
如果有外网环境，可以使用 OpenAI
如果不想用云服务，可以配置 Ollama 本地运行

步骤 3：启动服务

bash

# 构建并启动所有服务
docker-compose up -d

命令解释：

docker-compose：Docker 编排工具
up：启动服务
-d：后台运行（detached 模式）

步骤 4：查看启动日志

bash

# 查看所有服务日志
docker-compose logs -f

# 只查看后端日志
docker-compose logs -f backend

# 只查看前端日志
docker-compose logs -f frontend

# 按 Ctrl+C 退出日志查看

步骤 5：验证服务

bash

# 检查容器运行状态
docker-compose ps

# 应该看到类似这样的输出：
# NAME              STATUS
# itops-backend     Up (healthy)
# itops-frontend    Up

# 测试后端健康接口
curl http://localhost:3001/health

步骤 6：访问应用

打开浏览器访问：

前端页面: http://localhost:8080
后端 API: http://localhost:3001/health

2.7 方式三：本地开发模式（热重载）

如果你要修改代码，这是最适合你的方式。

方式 3.1：使用 local-dev 脚本（推荐）

项目提供了专门的本地开发环境配置。

Windows：

bash

cd local-dev
start-dev.bat

Linux/Mac：

bash

cd local-dev
chmod +x start-dev.sh
./start-dev.sh

这个脚本会：

使用 Docker 启动数据库容器
启动后端开发服务器（tsx watch 热重载）
启动前端开发服务器（Vite 热重载）

方式 3.2：手动分别启动

如果你想更好地控制每个服务，可以手动启动。

步骤 1：安装后端依赖并启动

bash

# 进入后端目录
cd backend

# 安装依赖（首次运行）
npm install

# 启动开发服务器
npm run dev

你会看到类似输出：

🚀 ITOps Agent Platform Backend running on 0.0.0.0:3001
📡 WebSocket server ready
🌍 Environment: development

后端会在 http://localhost:3001 运行，修改代码后会自动重新编译。

步骤 2：安装前端依赖并启动

打开新的命令行窗口，然后：

bash

# 进入前端目录
cd frontend

# 安装依赖（首次运行）
npm install

# 启动开发服务器
npm run dev

你会看到类似输出：

  VITE v5.0.8  ready in 300 ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose
  ➜  press h + enter to show help

前端会在 http://localhost:5173 运行，修改代码后浏览器会自动刷新。

访问地址：

前端开发服务器: http://localhost:5173
后端 API: http://localhost:3001

💡 开发模式的优势：
修改 TypeScript 代码后即时重新编译
修改前端组件后浏览器即时刷新
完整的错误提示和堆栈追踪

2.8 默认账号

部署完成后，使用以下默认账号登录：

字段	值
用户名	`admin`
密码	`admin`（一键脚本部署时可能显示随机密码）

⚠️ 安全提示：首次登录后，系统会强制要求你修改密码！这是为了保护系统安全。

2.9 常用运维命令

项目启动后，你可能需要执行一些运维操作。

停止服务

Docker Compose：

bash

# 停止所有服务
docker-compose down

# 停止并删除数据卷（⚠️ 会丢失数据！）
docker-compose down -v

本地开发模式：

在运行开发服务器的命令行窗口中按 Ctrl+C。

重启服务

bash

# 重启所有服务
docker-compose restart

# 只重启后端
docker-compose restart backend

# 只重启前端
docker-compose restart frontend

更新代码

bash

# 拉取最新代码
git pull origin main

# 如果使用 Docker，重新构建
docker-compose up -d --build

查看容器资源使用

bash

# 查看 CPU 和内存使用
docker stats

进入容器内部

bash

# 进入后端容器
docker exec -it itops-backend sh

# 进入前端容器
docker exec -it itops-frontend sh

# 退出容器
exit

备份数据库

bash

# 使用备份 API（需要先登录获取 Token）
curl -X POST http://localhost:3001/api/backups \
  -H "Authorization: Bearer YOUR_TOKEN"

# 或者手动复制数据库文件（Docker 方式）
docker cp itops-backend:/app/backend/data/app.db ./backup-app.db

2.10 验证环境

让我们全面检查一下部署是否成功。

2.10.1 检查服务状态

bash

# Docker 方式
docker ps
# 应该看到 backend 和 frontend 两个容器

# 本地开发方式
# 查看后端输出，应该显示 "running on 0.0.0.0:3001"
# 查看前端输出，应该显示 "Local: http://localhost:5173/"

2.10.2 检查后端 API

bash

# 健康检查（不需要认证）
curl http://localhost:3001/health

# 应该返回类似：
# {"status":"healthy","timestamp":"2026-05-27T10:00:00.000Z"}

2.10.3 检查前端

打开浏览器访问 http://localhost:8080（Docker）或 http://localhost:5173（本地开发），你应该能看到：

登录页面
精美的粒子背景动画
登录表单

2.10.4 检查 WebSocket

登录成功后，打开浏览器开发者工具（按 F12）：

切换到 Console 标签
应该没有红色错误信息
切换到 Network 标签
筛选 WS（WebSocket）
应该能看到一个 WebSocket 连接

2.11 常见问题与解决方案

问题 1：端口被占用

症状：启动时提示 Port 3001 is already in use 或 Port 8080 is already in use。

原因：其他程序正在使用该端口。

解决方案：

bash

# Windows - 查找占用端口的进程
netstat -ano | findstr :3001

# Mac/Linux
lsof -i :3001

# 杀掉占用进程（替换 PID 为实际进程号）
# Windows
taskkill /PID 1234 /F

# Mac/Linux
kill -9 1234

或者修改端口：

env

# 修改 .env 文件中的端口
PORT=3002

# 修改 docker-compose.yml 中的端口映射
ports:
  - "3002:3001"

问题 2：Docker 无法拉取镜像

症状：docker pull 超时或失败。

原因：网络问题或镜像仓库访问受限。

解决方案：

bash

# 使用国内镜像加速器
# 编辑 Docker Desktop 的 daemon.json
# 添加：
{
  "registry-mirrors": ["https://docker.mirrors.ustc.edu.cn"]
}

# 或者使用简化版配置（从源码构建）
docker-compose -f docker-compose.simple.yml up -d --build

问题 3：npm install 很慢

症状：安装依赖时速度非常慢或卡住。

解决方案：

bash

# 使用淘宝镜像源
npm config set registry https://registry.npmmirror.com

# 或者使用 pnpm（比 npm 快很多）
npm install -g pnpm
pnpm install

问题 4：前端页面空白

症状：访问前端页面显示空白。

排查步骤：

打开浏览器开发者工具（F12）
查看 Console 是否有错误
查看 Network 是否有请求失败

常见原因：

后端未启动 → 启动后端
API 地址配置错误 → 检查 vite.config.ts 中的代理配置
Token 无效 → 清除 localStorage，重新登录

问题 5：数据库文件权限问题

症状：后端启动失败，提示 SQLITE_CANTOPEN。

解决方案：

bash

# Docker 方式 - 确保 volume 挂载正确
docker-compose down
docker-compose up -d

# 本地开发方式 - 确保有 data 目录和写权限
mkdir -p backend/data
chmod 755 backend/data

问题 6：PowerShell 不允许运行脚本

症状：deploy.ps1 cannot be loaded because running scripts is disabled on this system.

解决方案：

powershell

# 以管理员身份运行 PowerShell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

本章小结

核心知识点回顾

✅ 项目需要 Node.js、Git、Docker 三个必需软件
✅ VS Code 是强烈推荐的代码编辑器
✅ 项目提供了三种启动方式：一键脚本、Docker Compose、本地开发
✅ 新手推荐使用一键脚本部署（deploy.ps1 / deploy.sh）
✅ 开发推荐使用本地开发模式（热重载）
✅ 默认管理员账号是 admin/admin
✅ 首次登录后系统会强制修改密码
✅ 使用 docker-compose logs -f 查看服务日志
✅ 使用 docker-compose down 停止服务
✅ 常见问题都有对应的解决方案

常见误区提醒

误区	正确理解
"必须安装所有软件才能开始"	一键脚本部署只需要 Docker！
"Docker 很复杂"	项目封装好了，一条命令就行
"本地开发很麻烦"	有热重载支持，改代码即时看效果
"API 密钥必须配置"	不配置也能运行，只是 AI 功能不可用

本章练习

基础练习

环境检查：在你的电脑上运行以下命令，记录版本号：
bash
```
node --version
npm --version
git --version
docker --version
```
获取代码：使用 Git 克隆项目到本地
启动项目：使用一键脚本部署，验证能正常访问登录页面

进阶练习

Docker Compose 部署：
- 复制 .env.example 为 .env
- 修改必要配置
- 使用 docker-compose up -d 启动
- 验证所有服务正常
本地开发模式：
- 分别启动后端和前端
- 修改前端代码，观察热重载效果
- 查看后端日志
运维操作：
- 停止所有服务
- 查看历史日志
- 重新启动服务

思考题

三种部署方式各有什么优缺点？你的场景适合用哪种？
如果端口 3001 被占用了，你会怎么处理？
Docker 容器中的数据是持久的吗？如果删除容器，数据还在吗？

第2章 环境准备与快速上手 ​

作者 ​

许可证 ​

本章导读 ​

本章学习目标 ​

前置知识要求 ​

预计学习时间 ​

2.1 环境要求 ​

2.1.1 必需软件 ​

2.1.2 可选软件 ​

2.2 安装必需软件 ​

2.2.1 安装 Node.js ​

2.2.2 安装 Git ​

2.2.3 安装 Docker ​

2.2.4 安装 VS Code（强烈推荐） ​

2.3 获取项目代码 ​

方式一：使用 Git 克隆（推荐） ​

方式二：下载 ZIP 压缩包 ​

2.4 部署方式选择 ​

2.5 方式一：一键脚本部署（推荐新手） ​

Windows 用户 ​

Linux/Mac 用户 ​

验证部署成功 ​

2.6 方式二：Docker Compose 部署 ​

步骤 1：配置环境变量 ​

步骤 2：编辑 .env 文件 ​

步骤 3：启动服务 ​

步骤 4：查看启动日志 ​

步骤 5：验证服务 ​

步骤 6：访问应用 ​

2.7 方式三：本地开发模式（热重载） ​

方式 3.1：使用 local-dev 脚本（推荐） ​

方式 3.2：手动分别启动 ​

2.8 默认账号 ​

2.9 常用运维命令 ​

停止服务 ​

重启服务 ​

更新代码 ​

查看容器资源使用 ​

进入容器内部 ​

备份数据库 ​

2.10 验证环境 ​

2.10.1 检查服务状态 ​

2.10.2 检查后端 API ​

2.10.3 检查前端 ​

2.10.4 检查 WebSocket ​

2.11 常见问题与解决方案 ​

问题 1：端口被占用 ​

问题 2：Docker 无法拉取镜像 ​

问题 3：npm install 很慢 ​

问题 4：前端页面空白 ​

问题 5：数据库文件权限问题 ​

问题 6：PowerShell 不允许运行脚本 ​

本章小结 ​

核心知识点回顾 ​

常见误区提醒 ​

本章练习 ​

基础练习 ​

进阶练习 ​

思考题 ​

延伸阅读 ​

官方资源 ​

技术学习 ​

进阶阅读 ​

第2章环境准备与快速上手

作者

许可证

本章导读

本章学习目标

前置知识要求

预计学习时间

2.1 环境要求

2.1.1 必需软件

2.1.2 可选软件

2.2 安装必需软件

2.2.1 安装 Node.js

2.2.2 安装 Git

2.2.3 安装 Docker

2.2.4 安装 VS Code（强烈推荐）

2.3 获取项目代码

方式一：使用 Git 克隆（推荐）

方式二：下载 ZIP 压缩包

2.4 部署方式选择

2.5 方式一：一键脚本部署（推荐新手）

Windows 用户

Linux/Mac 用户

验证部署成功

2.6 方式二：Docker Compose 部署

步骤 1：配置环境变量

步骤 2：编辑 .env 文件

步骤 3：启动服务

步骤 4：查看启动日志

步骤 5：验证服务

步骤 6：访问应用

2.7 方式三：本地开发模式（热重载）

方式 3.1：使用 local-dev 脚本（推荐）

方式 3.2：手动分别启动

2.8 默认账号

2.9 常用运维命令

停止服务

重启服务

更新代码

查看容器资源使用

进入容器内部

备份数据库

2.10 验证环境

2.10.1 检查服务状态

2.10.2 检查后端 API

2.10.3 检查前端

2.10.4 检查 WebSocket

2.11 常见问题与解决方案

问题 1：端口被占用

问题 2：Docker 无法拉取镜像

问题 3：npm install 很慢

问题 4：前端页面空白

问题 5：数据库文件权限问题

问题 6：PowerShell 不允许运行脚本

本章小结

核心知识点回顾

常见误区提醒

本章练习

基础练习

进阶练习

思考题

延伸阅读

官方资源

技术学习

进阶阅读