快速开始

本页说明如何从源码启动 webos v2。开发模式下，前端服务由后端统一代理到 9099 端口。

环境要求

• Go 1.24.6 或更高版本
• Node.js 22.19.0 或更高版本
• Git
• 可选：MySQL、Redis、RocketMQ

轻量启动

首次体验不需要额外安装 MySQL、Redis 或 RocketMQ。可以先使用 SQLite、本地缓存和内存消息队列运行。

获取源码

git clone https://github.com/fs185085781/v9os.git
cd v9os

启动后端

进入后端目录并安装 Go 依赖：

cd api
go mod tidy
go run cmd/console/main.go

也可以先编译再运行：

go build -o bin/console.exe ./cmd/console/main.go
./bin/console.exe

Windows 下编译产物为 console.exe；Linux 与 macOS 可以去掉扩展名。

启动前端

打开另一个终端：

cd web
npm install
npm run dev

开发模式下前端开发服务通常运行在 9098，但页面会由后端代理到 9099。

访问系统

浏览器打开：

http://127.0.0.1:9099

默认管理员：

账号：admin
密码：123456

首次登录后应立即修改默认密码。

编译合体程序

webos v2 可以把前端静态资源内置进 Go 程序：

cd util
go run build.go

编译完成后：

• Windows：运行合体包目录中的 v9os.exe
• Linux：为程序增加执行权限后运行
• macOS：按对应平台产物运行

Linux 示例：

chmod +x v9os
./v9os

合体模式下前端不再占用独立端口，统一从 9099 提供。

推荐阅读路线

开发目标	下一步
新增主程序中的业务模块	内核业务开发
理解启动、迁移与分布式运行	架构原理
开发带 Go 后端能力的插件	主程序插件
开发纯前端页面	前端插件
接入独立 Web 程序	第三方插件
接入已有 URL	远程应用

常见启动问题

数据库表没有创建

自动迁移由版本号变化触发。检查 api/internal/config/version.json 与运行目录 init.json 的版本是否不同，并确认模型在 init() 中完成迁移注册。

页面可以打开但插件不可用

检查插件表中的 Code、PluginType、Status、调试端口和插件目录是否一致。

更多排查步骤见疑难解答。