Atlas/README.md

go-vue-template

Go + Vue 单体应用脚手架。一个二进制同时提供 REST API 与管理台 UI，前端通过 go:embed 嵌入，适合内部工具、管理后台、网关控制台等场景。

特性

• 单体部署：API 与 SPA 同进程、同端口，生产环境无需 Node.js
• 分层清晰：cmd → api → service → store，职责边界明确
• 开箱即用：登录鉴权、设置页、审计日志、i18n、Docker 多阶段构建
• 纯 Go 编译：SQLite 使用 modernc.org/sqlite，CGO_ENABLED=0 可交叉编译
• 可演进：goose SQL 迁移、settings KV 配置、Pinia 状态管理

快速开始

# 开发模式（两个终端）
make run          # 后端 :8080
make dev-web      # 前端 :5173，/api 代理到 8080

# 生产构建
make build
./dist/app

# Docker
docker compose up -d

默认管理员密码：admin（可在设置页修改）。

---

使用本模板

1. Fork 或 clone 本仓库作为新项目起点
2. 修改 Go module 名：全局替换 github.com/rose_cat707/go-vue-template 为你的模块路径
3. 修改应用标识：更新 settings 默认值、web/ 中的品牌文案、镜像名等
4. 按需扩展：在 internal/ 增加业务包，在 web/src/views/ 增加页面

# 示例：批量替换 module 名
find . -type f \( -name '*.go' -o -name 'go.mod' \) \
  -exec sed -i '' 's|github.com/rose_cat707/go-vue-template|github.com/you/your-app|g' {} +

---

架构

┌─────────────────────────────────────────────────────────┐
│                     单一 Go 进程                          │
│  ┌──────────────┐  ┌──────────────┐  ┌───────────────┐  │
│  │ /api/v1/*    │  │ /health      │  │ /* (SPA)      │  │
│  │ REST API     │  │ 健康检查      │  │ embed 静态资源  │  │
│  └──────┬───────┘  └──────────────┘  └───────────────┘  │
│         │                                                │
│  ┌──────▼──────────────────────────────────────────┐    │
│  │ api (HTTP)  →  service (编排)  →  store (持久化)  │    │
│  └─────────────────────────────────────────────────┘    │
│         │                                                │
│  ┌──────▼──────┐                                        │
│  │ SQLite WAL  │  {data}/app.db                         │
│  └─────────────┘                                        │
└─────────────────────────────────────────────────────────┘
         ▲                          ▲
         │ 生产：同一端口              │ 开发：Vite :5173 代理 /api
         └──────────────────────────┘

分层约定

层	路径	职责
入口	cmd/app/	解析参数、初始化依赖、启动 HTTP、优雅关闭
HTTP	internal/api/	路由注册、中间件、请求/响应、SPA 静态服务
业务	internal/service/	跨模块编排，注入 Store 与领域服务
持久化	internal/store/	数据库连接、迁移、仓储方法
配置	internal/settings/	配置键常量、默认值、展示脱敏、提交校验
前端	web/	Vue SPA 源码，构建产物复制到 internal/api/static/

原则：

• Handler 只做 HTTP 适配，不写复杂业务逻辑
• Store 封装 SQL，不暴露 *sql.DB 给 Handler
• 前端构建产物不提交 dist，仅保留 static/index.html 占位以保证 go test / CI 可通过

---

目录结构

.
├── cmd/app/                 # 进程入口
├── internal/
│   ├── api/
│   │   ├── handlers.go      # 路由与 Handler
│   │   ├── auth_token.go    # Token 签发与校验
│   │   ├── static.go        # go:embed SPA
│   │   └── static/          # 前端构建产物（占位 index.html 已提交）
│   ├── service/             # 业务编排
│   ├── store/
│   │   ├── store.go
│   │   └── migrations/      # goose SQL 迁移
│   └── settings/            # 配置键与规范化
├── web/
│   ├── src/
│   │   ├── api/             # axios 客户端与类型
│   │   ├── components/      # 通用 UI 组件
│   │   ├── i18n/            # 多语言
│   │   ├── layouts/         # 布局
│   │   ├── router/          # 路由与鉴权守卫
│   │   ├── stores/          # Pinia
│   │   ├── styles/          # 主题变量
│   │   └── views/           # 页面
│   ├── vite.config.ts
│   └── package.json
├── Makefile
├── Dockerfile
├── docker-compose.yml
├── go.mod
└── .gitea/                  # Gitea Actions CI
    ├── README.md
    ├── workflows/ci.yml
    └── act-runner/          # runner 部署参考（可选）

---

技术栈

层级	选型	说明
后端	Go 1.25 + Gin	HTTP 路由与中间件
数据库	SQLite (modernc.org/sqlite)	纯 Go 驱动，无 CGO
迁移	goose v3 (embed SQL)	版本化、可回滚
前端	Vue 3 + Vite + TypeScript	Composition API + <script setup>
UI	Element Plus	组件库与图标
状态	Pinia	全局状态（认证、语言等）
路由	vue-router (History)	路由守卫 + /auth/status
HTTP	axios	Bearer Token，401 全局跳转
i18n	vue-i18n	与 Element Plus locale 联动

---

API 规范

前缀： /api/v1

鉴权

接口	说明
POST /api/v1/auth/login	登录，返回 { "token": "..." }
GET /api/v1/auth/status	查询 { "enabled": true | false }
受保护路由	Header: Authorization: Bearer <token>

当 auth_enabled 不为 "true" 时，受保护路由跳过鉴权（便于本地调试）。

响应格式

// 成功 — 按场景选用
{ "ok": true }
{ "items": [...], "total": 42 }
{ "app_name": "App", "data_dir": "./data" }

// 错误 — 统一字段
{ "error": "human readable message" }

HTTP 状态码

码	含义
400	请求参数错误
401	未授权
404	资源不存在
500	服务器内部错误

分页

列表接口支持 ?limit=（默认 50，最大 500）与 ?offset=，响应含 items 与 total。

---

配置

启动参数与环境变量

来源	名称	默认	说明
CLI	-data	./data	数据目录（SQLite 等）
CLI	-addr	:8080	HTTP 监听地址
Env	APP_DATA	—	覆盖 -data
Env	APP_ADDR	—	覆盖 -addr

运行时配置（SQLite KV）

业务配置存储在 settings 表，可通过 Web 设置页修改，无需重启：

键	说明
app_name	应用名称
admin_password	管理员密码（GET 时脱敏）
auth_enabled	是否启用认证（true / false）
ui_locale	界面语言（zh-CN / en）

新增配置项：在 internal/settings/keys.go 定义键与默认值，并编写 goose 迁移插入初始值。

---

开发工作流

双进程开发（推荐）

# 终端 1 — 后端
make run

# 终端 2 — 前端热更新
make dev-web
# 浏览器访问 http://localhost:5173

Vite 将 /api 代理到 http://127.0.0.1:8080。

单体构建

make build
# 1. web: npm run build → web/dist
# 2. cp web/dist/* → internal/api/static/
# 3. go build → dist/app（embed 前端）

常用命令

命令	作用
make run	运行后端（不 embed 最新前端）
make dev-web	启动 Vite 开发服务器
make build	构建含 embed 前端的完整二进制
make test	运行 Go 测试
make tidy	go mod tidy
make clean	清理构建产物

---

Docker 部署

make docker-build
docker run -d -p 8080:8080 -v app-data:/data go-vue-template:latest

或使用：

docker compose up -d

镜像采用多阶段构建（Node 编译前端 → Go 编译 → Alpine 运行），以非 root 用户运行，数据持久化至 /data 卷。

---

Gitea Actions CI

仓库已包含 .gitea/workflows/ci.yml，push 到 main/master 或打 v* tag 时自动：

1. 运行 go test ./...
2. 多架构 Docker 构建并推送到 Gitea Container Registry

一次性配置：

项	说明
Runner	标签 ubuntu-latest，挂载 /var/run/docker.sock
Secret	REGISTRY_TOKEN（PAT，write:package）
Variable	REGISTRY=你的公网 Gitea 域名（内网部署时必填）

PR 仅验证 Dockerfile 构建，不推送镜像。详细说明见 .gitea/README.md。

---

扩展指南

新增 REST 接口

1. internal/store/migrations/00N_*.sql — 建表或改表
2. internal/store/store.go — 仓储方法
3. internal/api/handlers.go — 注册路由与 Handler
4. web/src/api/client.ts — 类型定义与 API 调用
5. web/src/views/ + web/src/router/index.ts — 页面与路由

新增业务模块

在 internal/ 下新建包（如 internal/worker/），在 service.App 中注入，由 api 层调用。保持 Handler 薄、领域逻辑内聚。

前端规范

• 页面使用 PageHeader + AppCard 布局
• 样式变量定义在 web/src/styles/theme.css
• 文案走 vue-i18n，避免硬编码
• API 调用统一经 web/src/api/client.ts

---

License

MIT — 见 LICENSE