🚀 AstronRPA 快速开始指南

快速、简单、强大的 RPA 自动化平台部署指南

</div>

📋 目录

系统要求
环境准备
部署架构说明
服务端部署 (Docker)
客户端部署 (本地)
开发环境搭建
常见问题

💻 系统要求

操作系统

操作系统	版本要求	支持状态
Windows	10/11	✅ 主要支持

硬件配置

配置项	最低要求	推荐配置
CPU	2 核心	4 核心+
内存	4GB	8GB+
磁盘	10GB 可用空间	20GB+
网络	稳定的互联网连接	-

环境依赖

工具	版本要求	说明
Node.js	>= 22	JavaScript 运行时
Python	3.13.x	RPA 引擎核心
Java	JDK 8+	后端服务运行时
pnpm	>= 9	Node.js 包管理器
UV	0.8+	Python 包管理工具
7-Zip	-	创建部署归档文件
SWIG	-	连接 Python 与 C/C++

🛠️ 环境准备

1️⃣ Python (3.13.x)

🐍 核心依赖 · AstronRPA 需要 Python 3.13.x 版本作为 RPA 引擎核心

方式 1: 官方下载（推荐）

bash

# 访问 https://www.python.org/downloads/
# 下载 Python 3.13.x 版本并安装

方式 2: 使用 Winget

bash

winget install Python.Python.3.13

方式 3: 使用 Chocolatey

bash

choco install python --version=3.13.x

</details>

📍 Python 安装路径说明

安装完成后，您需要记住 Python 的安装路径，因为后续配置可能会用到：

安装方式	典型路径
🟢 官方安装包	`C:\Users\{用户名}\AppData\Local\Programs\Python\Python313\`
🔵 Chocolatey	`C:\Python313\` 或 `C:\tools\python3\`

💡 重要提示：

✓ Python 可执行文件：{安装目录}\python.exe
✓ 示例：C:\Users\{用户名}\AppData\Local\Programs\Python\Python313\python.exe

2️⃣ UV (0.8+)

⚡ 快速包管理 · 新一代 Python 包管理器，比 pip 快 10-100 倍

powershell

# 方式 1: 官方安装脚本（推荐）
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# 方式 2: 使用 pip
pip install uv

# 方式 3: 使用 Chocolatey
choco install uv

</details>

✅ 验证安装

bash

uv --version
# ✓ 应该显示类似：uv 0.8.x (xxxxx)

📖 了解更多: UV 官方文档

3️⃣ pnpm (9+)

📦 高效包管理 · 节省磁盘空间的 Node.js 包管理器

bash

# 方式 1: 使用 npm（推荐）
npm install -g pnpm@latest

# 方式 2: Windows PowerShell
iwr https://get.pnpm.io/install.ps1 -useb | iex

# 方式 3: macOS/Linux
curl -fsSL https://get.pnpm.io/install.sh | sh -

# 方式 4: Homebrew (macOS)
brew install pnpm

</details>

✅ 验证安装

bash

pnpm --version
# ✓ 应该显示 9.x.x 或更高版本

📖 了解更多: pnpm 官方文档

4️⃣ Docker

🐳 容器化平台 · 用于服务端快速部署

平台	下载链接
🪟 Windows/Mac	Docker Desktop
🐧 Linux	Docker Engine

</details>

✅ 验证安装

bash

docker --version
docker compose --version
# ✓ 确认 Docker 和 Docker Compose 都已正确安装

5️⃣ 7-Zip

📦 压缩工具 · 用于创建部署归档文件

官网下载： https://www.7-zip.org/

下载并安装到系统，或解压到自定义目录

</details>

✅ 验证安装

bash

# 如果安装到系统路径
7z

# 或者使用完整路径
"C:\Program Files\7-Zip\7z.exe"

6️⃣ SWIG

🔗 接口生成器 · 用于连接 Python 与 C/C++ 程序

步骤 1：下载 SWIG

访问 http://www.swig.org/download.html
下载 swigwin-x.x.x.zip 解压到任意目录

步骤 2：添加到系统环境变量

将 swig.exe 所在目录添加到 PATH 环境变量
例如：C:\swig\swigwin-4.1.1

步骤 3：验证安装

bash

swig -version
# ✓ 确认 SWIG 已正确安装

</details>

🏗️ 部署架构说明

AstronRPA 采用 服务端-客户端 架构：

部署说明

服务端部署 - 使用 Docker 快速部署
- Web 管理界面
- 后端 API 服务
- 数据库和缓存
- AI 服务
客户端部署 - 使用打包脚本部署
- RPA 执行引擎
- 桌面管理应用
- 连接到服务端进行任务执行

🌐 服务端部署 (Docker)

快速部署 · 使用 Docker Compose 一键启动所有服务端组件

服务端提供 Web 管理界面、API 服务、数据库等核心服务。

📦 部署步骤

步骤 1️⃣: 克隆仓库

bash

git clone https://github.com/iflytek/astron-rpa.git
cd astron-rpa

步骤 2️⃣: 启动服务端

bash

# 进入 Docker 目录
cd docker

# 复制.env
cp .env.example .env

# 修改.env中casdoor的服务配置
CASDOOR_EXTERNAL_ENDPOINT="http://{YOUR_SERVER_IP}:8000"

# 🚀 启动所有服务
docker compose up -d

# 📊 检查服务状态
docker compose ps

<details> <summary>💡 <b>预期输出示例</b></summary>

NAME                STATUS              PORTS
robot-service       Up 30 seconds       0.0.0.0:8080->8080/tcp
ai-service          Up 30 seconds       0.0.0.0:8001->8001/tcp
openapi-service     Up 30 seconds       0.0.0.0:8002->8002/tcp
mysql               Up 30 seconds       0.0.0.0:3306->3306/tcp
redis               Up 30 seconds       0.0.0.0:6379->6379/tcp

</details>

步骤 3️⃣: 验证服务端部署

bash

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

🔧 服务端管理命令

bash

# 🛑 停止服务
docker compose down

# 🔄 重启服务
docker compose restart

# 📋 查看特定服务日志
docker compose logs -f robot-service

# ⬆️ 更新镜像
docker compose pull
docker compose up -d

📖 详细配置: 服务端部署指南

💻 客户端部署 (本地)

本地部署 · 在执行 RPA 任务的机器上部署引擎和桌面应用

客户端包含 RPA 执行引擎和桌面管理应用，需要部署到执行 RPA 任务的机器上。

🎯 一键打包部署方式

适合生产环境和最终用户。

🪟 Windows 环境

<details> <summary><b>步骤 1️⃣: 准备 Python 环境</b></summary>

确保已安装 Python 3.13.x 到本地目录（如 C:\Python313）。

环境目录结构：

Python313/
├─ DLLs/
├─ Doc/
├─ include/
├─ Lib/
├─ libs/
├─ Scripts/
├─ tcl/
│
├─ LICENSE.txt
├─ NEWS.txt
├─ python.exe
├─ python3.dll
├─ python313.dll
├─ pythonw.exe
├─ vcruntime140.dll
└─ vcruntime140_1.dll

⚠️ 重要提示： 请使用纯净的 Python 安装，避免安装额外第三方包，以减小打包体积。

</details> <details> <summary><b>步骤 2️⃣: 运行打包脚本</b></summary>

基础用法

在项目根目录执行构建脚本：

bash

# 🚀 完整构建（引擎 + 前端）
./build.bat -p "C:\Program Files\Python313\python.exe"

# 或使用默认配置（如果 Python 在默认路径）
./build.bat

# ⏳ 请等待操作完成
# ✅ 当控制台显示 "Full Build Complete!" 时表示构建成功

执行流程：

✅ 检测/复制 Python 环境到目录 build/python_core
✅ 安装 RPA 引擎依赖包
✅ 压缩 Python 包到目录 resources/python_core.7z
✅ 安装前端依赖
✅ 构建桌面应用

高级选项

查看所有可用参数：

bash

./build.bat --help

常用参数组合：

bash

# 🔧 指定 Python 路径
./build.bat --python-exe "D:\Python313\python.exe"

# 🔧 指定 7-Zip 路径
./build.bat --sevenz-exe "D:\7-Zip\7z.exe"

# ⏭️ 只构建引擎，跳过前端
./build.bat --skip-frontend

# ⏭️ 只构建前端，跳过引擎
./build.bat --skip-engine

# 🔀 组合使用短参数
./build.bat -p "D:\Python313\python.exe" -s "D:\7-Zip\7z.exe"

参数说明：

参数	简写	说明
`--python-exe <路径>`	`-p`	指定 Python 可执行文件路径
`--sevenz-exe <路径>`	`-s`	指定 7-Zip 可执行文件路径
`--skip-engine`	-	跳过引擎（Python）构建
`--skip-frontend`	-	跳过前端构建
`--help`	`-h`	显示帮助信息

手动构建前端

如果需要单独手动构建前端，可以执行以下步骤：

<details> <summary>点击展开手动构建步骤</summary>

bash

cd frontend

# 📦 安装依赖
pnpm install

# ⚙️ 配置环境变量
pnpm set-env

# 🖥️ 构建桌面应用
pnpm build:desktop

提示： 使用 build.bat --skip-engine 可以自动完成上述前端构建步骤。

</details> </details> <details> <summary><b>步骤 3️⃣: 安装 Exe 安装包</b></summary>

打包完成路径：

/frontend/packages/electron-app/dist/

双击 Exe 文件进行安装。

</details> <details> <summary><b>步骤 4️⃣: 配置服务端地址</b></summary>

安装好后在安装目录下的 resources/conf.yaml 中修改服务端地址：

yaml

# 32742为默认端口，如有修改自行变更
remote_addr: http://YOUR_SERVER_ADDRESS:32742/
skip_engine_start: false

💡 提示： 将 YOUR_SERVER_ADDRESS 替换为实际的服务端地址

</details>

🌐 开发服务器地址

服务	地址	说明
🖥️ 桌面应用	自动启动窗口	桌面客户端
🔌 后端服务 API	http://localhost:32742	后端网关服务Nginx
🔑 Casdoor服务 API	http://localhost:8000	认证服务Casdoor

🔍 完整部署验证

✅ 步骤 1: 服务端检查

bash

# 📊 检查 Docker 服务状态
docker compose ps

# 🔍 验证 API 响应
在浏览器访问 http://{YOUR_SERVER_IP}:32742/api/rpa-auth/user/login-check （32742为默认端口，如有修改自行变更）
如果显示 {"code":"900001","data":null,"message":"unauthorized"} 则表示部署正确且能正常联通。

✅ 步骤 2: Casdoor服务检查

bash

# 🔍 验证 Casdoor 服务
浏览器打开http://localhost:8000
出现casdoor认证页面

后续验证：

✓ 在 Web 界面中检查客户端节点状态
✓ 创建简单测试任务验证执行

❓ 常见问题

🌐 服务端相关

<details> <summary><b>Q: Docker 服务启动失败？</b></summary>

bash

# 🔍 检查端口占用
netstat -tulpn | grep :8080

# ✅ 检查 Docker 状态
docker --version
docker compose --version

# 📋 查看详细错误日志
docker compose logs

常见原因：

❌ 端口被占用（8080、3306、6379）
❌ Docker 服务未启动
❌ 资源不足（内存/磁盘空间）

</details> <details> <summary><b>Q: 数据库连接失败？</b></summary>

bash

# 📊 检查 MySQL 容器状态
docker compose ps mysql

# 📝 查看 MySQL 日志
docker compose logs mysql

# 🔄 重启数据库服务
docker compose restart mysql

</details>

💻 客户端相关

<details> <summary><b>Q: Python 环境复制失败？</b></summary>

bash

# 🔍 检查 Python 安装路径
where python  # Windows
which python  # Linux/macOS

# 🔍 检查是否复制的是Python可执行文件

✖️ ./build.bat -p "C:\\Python313"
✔️ ./build.bat -p "C:\\Python313\\python.exe"

解决方案：

✓ 确保 Python 目录存在且可读
✓ 使用管理员权限运行脚本
✓ 检查磁盘空间是否充足

</details> <details> <summary><b>Q: 打包脚本执行失败？</b></summary>

bash

# ✅ 检查准备阶段的所有依赖是否安装完整

# 💾 检查磁盘空间
dir  # Windows 检查可用空间

</details>

🔌 连接相关

<details> <summary><b>Q: 客户端无法连接服务端？</b></summary>

bash

# 🌐 检查网络连通性
# 用浏览器直接打开下方连接，看是否有结果返回
# http://localhost:32742 可替换为你部署的服务器的地址+端口
http://localhost:32742/api/rpa-auth/user/login-check

# 🛡️ 检查防火墙设置
# Windows: 控制面板 > 系统和安全 > Windows Defender 防火墙
# Linux: ufw status

# ✅ 检查服务端健康状态
curl http://localhost:32742/health

常见原因：

❌ 服务端未启动
❌ 防火墙拦截
❌ 网络不通
❌ 配置文件中地址错误

</details> <details> <summary><b>Q: WebSocket 连接失败？</b></summary>

bash

# 🔌 检查 WebSocket 端点
curl -i -N -H "Connection: Upgrade" -H "Upgrade: websocket" \
     http://localhost:8080/ws

# 🔍 检查代理设置
echo $http_proxy
echo $https_proxy

解决方案：

✓ 确认服务端 WebSocket 服务正常
✓ 检查是否有代理影响连接
✓ 验证防火墙规则

</details>

🏗️ 构建相关

<details> <summary><b>Q: 前端构建失败？</b></summary>

bash

# 🧹 清理缓存
pnpm store prune
rm -rf node_modules pnpm-lock.yaml

# 📦 重新安装
pnpm install

# ✅ 检查 Node.js 版本
node --version  # 需要 22+

常见原因：

❌ Node.js 版本不符合要求
❌ 依赖包版本冲突
❌ 缓存损坏

</details>

📞 获取帮助

遇到问题？我们随时为您提供帮助！

</div>

渠道	链接	说明
📧 技术支持	[email protected]	直接联系技术团队
💬 社区讨论	GitHub Discussions	与社区交流心得
🐛 问题报告	GitHub Issues	提交 Bug 和功能建议
📖 完整文档	项目文档	查阅详细使用文档

🎯 下一步

✨ 恭喜您完成部署！现在可以开启 RPA 自动化之旅了 ✨

</div>

步骤	内容	链接
1️⃣	📚 学习使用	阅读用户指南了解如何创建 RPA 流程
2️⃣	🔧 组件开发	参考组件开发指南开发自定义组件
3️⃣	🤝 参与贡献	查看贡献指南参与项目开发
4️⃣	📱 部署到生产	参考生产部署指南进行生产环境部署

🎉 部署完成！

您已成功部署 AstronRPA 服务端和客户端

现在可以开始创建强大的 RPA 自动化流程了！

Happy Automating! 🤖✨

</div>