开发环境

本指南帮助你搭建 Web.Casa 的本地开发环境。

前置要求

要求	版本	说明
Go	1.26+	后端编译器
Node.js	24+	前端构建工具链
npm	随 Node.js 附带	包管理器
GCC	任意近期版本	CGo 编译所需（SQLite）
Git	任意近期版本	版本控制

可选： 如需测试容器管理功能，请安装 Docker。核心开发不要求 Docker。

开发已在 Linux 和 macOS 上测试通过。

克隆仓库

1. 在 GitHub 上 Fork Web.Casa 仓库
2. 克隆你的 Fork：

git clone https://github.com/YOUR_USERNAME/webcasa.git
cd webcasa

安装依赖

# Go 后端依赖
go mod download

# 前端依赖
cd web && npm install

启动开发服务器

需要两个终端，分别运行后端和前端。

终端 1 — 后端：

go run .

API 服务启动于 **http://localhost:39921**。

终端 2 — 前端：

cd web && npm install && npm run dev

前端开发服务器启动于 http://localhost:5173**，支持热模块替换（HMR）。API 请求自动代理**到 Go 后端，无需配置 CORS。

提示： 开发时在浏览器中打开 **http://localhost:5173**。前端开发服务器提供即时 HMR 更新。后端 39921 端口提供编译后的生产前端和 API 代理。

数据库

Web.Casa 使用 SQLite，无需配置外部数据库。首次运行时会在 data/ 目录中自动创建开发数据库文件。

热更新行为

• 前端 — Vite HMR 即时应用变更，无需刷新页面
• 后端 — 修改 Go 代码后需重新执行 go run .

构建生产版本

make build

此命令将 Go 后端（内嵌前端静态资源）编译为单个二进制文件。

项目结构

webcasa/
├── main.go                  # 入口文件
├── VERSION                  # 版本号（唯一版本来源）
├── Makefile                 # 构建任务
├── internal/
│   ├── config/              # 环境配置加载
│   ├── model/               # 数据模型（GORM 结构体）
│   ├── database/            # SQLite 初始化
│   ├── auth/                # JWT 认证
│   ├── caddy/               # Caddy 进程管理 + Caddyfile 渲染
│   ├── service/             # 业务逻辑
│   └── handler/             # HTTP 路由处理器
├── web/                     # React 19 前端
│   └── src/pages/           # 页面组件
├── install.sh               # 一键安装脚本
├── Dockerfile
└── docker-compose.yml