# ubibot-open-server

**Repository Path**: ubibot/ubibot-open-server

## Basic Information

- **Project Name**: ubibot-open-server
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-14
- **Last Updated**: 2026-09-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# UbiBot Open Server

[UbiBot Open](https://gitee.com/ubibot-open) 面向设备的后端与管理控制台——一个 Go API（设备身份、
数据接入、SQLite 存储），内嵌一个 React/Ant Design 管理控制台，最终构建成单个自包含的可执行文件。
它是一个小型多仓库生态的一部分；它和
[WS1B 固件](https://gitee.com/ubibot-open/ubibot-ws1b)、
[串口调试工具](https://gitee.com/ubibot-open/ubibot-serial-sync)、
[无需硬件的设备模拟器](https://gitee.com/ubibot-open/ubibot-open-simulator)以及
[协议/部署文档](https://gitee.com/ubibot-open/ubibot-open-doc)是怎么配合起来的，见
[组织主页](https://gitee.com/ubibot-open)。

> 这是一个开源的、面向内部/教学用途的物联网平台——不是 UbiBot 的商业平台，也不追求生产级的安全性
> 或完整性。哪些内容被有意排除在范围之外（设备认证签名、OTA、通用推送通道等），见
> [协议文档](https://gitee.com/ubibot-open/ubibot-open-doc/blob/main/protocol/hardware-communication-protocol.md#0-项目范围与本版本修订说明)。
> 唯一的例外是一条功能很窄、没有确认回执的指令通道（重启 / 修改上报间隔，
> [协议 §9](https://gitee.com/ubibot-open/ubibot-open-doc/blob/main/protocol/hardware-communication-protocol.md#9-指令下发管理员触发可选)），
> 在管理控制台的设备详情页中排队下发。

## 仓库结构

```
admin/        React + TypeScript + Ant Design 管理控制台（Vite）
server/       Go 后端——cmd/server 是入口，internal/ 存放具体实现
  cmd/        main.go：组装、启动引导、环境变量
  internal/
    api/      HTTP 处理函数 + 路由
    auth/     密码哈希、管理员会话
    model/    数据模型（GORM 结构体）
    protocol/ 面向设备的协议辅助代码
    store/    持久化（通过 GORM 使用 SQLite）
    webui/    把 admin/ 的构建产物嵌入 Go 可执行文件
docs/         内部设计文档（协议规范的权威源文件、功能待办清单）
build.sh / build.ps1   构建管理控制台、将其嵌入，并编译服务端可执行文件
```

## 快速开始

```bash
./build.sh        # Linux/macOS — 需要 Node.js/npm 和 Go 1.23+
# .\build.ps1      # Windows

./ubibot-server
# 打开 http://localhost:8080
```

API 和管理控制台由同一个地址提供服务。首次运行时（数据库中还没有管理员账号），日志会打印一个一次性
生成的 `admin` 密码——请记下来，它只会显示这一次。完整的操作步骤、环境变量，以及如何端到端验证一台
设备，见[部署指南](https://gitee.com/ubibot-open/ubibot-open-doc/blob/main/guides/deployment-flashing-guide.md#2-部署并启动后端ubibot-open-server)。

## 不用硬件测试

[ubibot-open-simulator](https://gitee.com/ubibot-open/ubibot-open-simulator) 是一个纯 C 编写的设备
模拟器，位于独立仓库中，使用的 HTTP 协议与真实的 WS1B 固件完全一致：

```bash
git clone https://gitee.com/ubibot-open/ubibot-open-simulator.git
cd ubibot-open-simulator
cmake -S . -B build && cmake --build build
./build/ub_device_sim --host 127.0.0.1 --port 8080
```

## 开发

- **后端**：`cd server && go build ./... && go test ./...`
- **管理控制台**（开发服务器，连接到一个正在运行的后端）：`cd admin && npm install && npm run dev`

## 文档

- [架构总览](https://gitee.com/ubibot-open/ubibot-open-doc/blob/main/architecture/overview.md)
  ——本仓库如何与固件、串口工具配合，以及这个后端自身的内部结构。
- [硬件通信协议](https://gitee.com/ubibot-open/ubibot-open-doc/blob/main/protocol/hardware-communication-protocol.md)
  ——本后端实现的设备↔服务端 HTTP 协议。
- [系统部署、烧录与上电指南](https://gitee.com/ubibot-open/ubibot-open-doc/blob/main/guides/deployment-flashing-guide.md)
  ——如何把本后端与固件、串口工具一起部署。
- [管理后台 API 参考](https://gitee.com/ubibot-open/ubibot-open-doc/blob/main/api/admin-api.md)
  / [开放 API 参考](https://gitee.com/ubibot-open/ubibot-open-doc/blob/main/api/open-api.md)
  ——本后端暴露的所有 `/api/admin/*` 和 `/api/open/v1/*` 路由。
- 本仓库中的 [docs/](docs/)——内部设计文档（不面向用户）：协议规范的权威源文件，以及管理控制台路线图
  背后的功能待办清单。

## 参与贡献

见[组织级 CONTRIBUTING.md](https://gitee.com/ubibot-open/.github/blob/main/CONTRIBUTING.md)。

## 许可证

[Apache License 2.0](LICENSE)。