Skip to content

LiteyukiStudio/devops

BranchesTags

Repository files navigation

Liteyuki DevOps logo

Liteyuki DevOps

面向个人开发者和小团队的 DevOps 应用交付平台。

文档站 · 产品方案 · 代码健康 SOP · 开发计划 · 开发规范

项目定位

Liteyuki DevOps 将代码仓库、镜像站、构建、部署、网关和域名打通，让开发者只需要维护代码、Dockerfile 和少量配置，就能把应用交付成一个可访问的服务。

第一阶段聚焦一条稳定闭环：

绑定仓库
  -> 平台构建镜像
  -> 推送制品库
  -> 部署到 Kubernetes / K3s
  -> 配置 Ingress / Traefik
  -> 分配域名
  -> 展示状态与发布记录

核心能力

模块 能力
项目与应用 项目空间、应用、成员和权限管理
认证准入 本地账号、OIDC、邀请/导入、准入策略
代码仓库 Gitea / GitHub 账号授权、仓库绑定、Webhook
平台构建 Worker 调度部署集群 Kubernetes Job，使用 BuildKit 构建并推送镜像
镜像站 Harbor / Gitea Registry / DockerHub 接入
部署发布 Kubernetes / K3s 部署、Release 记录、回滚
网关域名 Ingress / Traefik、自定义域名、HTTP Challenge 证书
站点配置 title、logo、favicon、登录页副标题等公开配置
体验基础 light / dark / system 主题、i18n、友好错误页

技术栈

领域 技术
后端 Go, Gin, GORM, PostgreSQL, Redis, Asynq, client-go, OpenAPI
前端 Vite, React, TypeScript, Tailwind CSS, shadcn/ui, TanStack Query
表单与体验 React Hook Form, Zod, i18next, react-i18next, Sonner
运维与构建 Docker Compose, Kubernetes Job, BuildKit, Traefik / Ingress
Python 工具链 uv

快速开始

启动开发依赖：

docker compose -f docker-compose-dev.yaml up -d

开发依赖 compose 使用独立项目名 liteyuki-devops-dev，并把 PostgreSQL / Redis 暴露到宿主机 5432 / 6379，供 go run 的 API、worker 和本地工具连接。

准备本地环境变量：

cp .env.example .env
cp .env.development.example .env.development
cp .env.worker.example .env.worker

启动 API：

go run ./cmd/api

启动 worker：

go run ./cmd/worker

启动前端：

pnpm --dir web install
pnpm --dir web dev

开发环境前端请求 /api/v1，由 Vite proxy 反代到 http://localhost:8080。

本地 minikube 部署联调

当 API / worker 运行在 Docker Compose 容器中时，集群 kubeconfig 不要使用宿主机专用的 https://127.0.0.1:<port> 和外链证书文件路径。默认 docker-compose*.yaml 不内置本地 minikube 域名映射；只有需要在容器内访问宿主机 minikube apiserver 时，再用本地 override 追加。

推荐为本地 minikube 预留统一域名：

  • 宿主机 /etc/hosts：127.0.0.1 dev.minikube.local
  • Docker Compose 容器：通过本地 override 将 dev.minikube.local 解析到宿主机网关
  • minikube apiserver 证书：启动 profile 时需要把 dev.minikube.local 加入 apiserver SAN

示例：

minikube -p liteyuki-devops start --apiserver-names=dev.minikube.local
kubectl config view --raw --minify --flatten > /tmp/liteyuki-devops.kubeconfig

如果 worker 跑在 Compose 容器里，可以新建不提交的 docker-compose-minikube.override.yaml：

services:
  worker:
    extra_hosts:
      - "dev.minikube.local:host-gateway"

再启动：

docker compose -f docker-compose-dev.yaml -f docker-compose-minikube.override.yaml up -d --build

然后将导出的 kubeconfig 中的 server 改为 https://dev.minikube.local:<apiserver-port>，再保存到平台运行集群配置。--flatten 必须保留，用于把 certificate-authority-data、client-certificate-data 和 client-key-data 内联到 kubeconfig，避免 worker 容器读取不到宿主机证书文件。

推荐开发拓扑

日常前后端开发最频繁，推荐宿主机运行 Vite 和 API，开发 compose 负责启动 PostgreSQL / Redis / worker：

flowchart LR
  Chrome["Chrome\nlocalhost:5173"] --> Vite["Vite dev server"]
  Vite -->|"/api/v1 proxy"| API["go run ./cmd/api\nlocalhost:8080"]
  API --> PG[("PostgreSQL\nlocalhost:5432")]
  API --> Redis[("Redis\nlocalhost:6379")]
  Worker["worker container"] --> PG
  Worker --> Redis
  Worker -->|BuildRun task| K8s["Kubernetes / K3s\nJob + BuildKit"]
  K8s --> Registry["Artifact Registry"]
Loading

启动开发依赖和异步组件：

docker compose -f docker-compose-dev.yaml up -d --build

构建任务由 API 写入 BuildRun / BuildJob 后投递到 worker；worker 根据部署配置所属环境解析运行集群，在对应项目命名空间内创建一次性 Kubernetes Job 执行 BuildKit 构建，并把日志、进度、镜像结果写回平台。API 和前端改动频繁时仍在宿主机运行，避免每次都重建完整容器栈。

开发 compose 不读取宿主机 .env.development；worker 使用 .env.worker。.env.development 只给宿主机 go run 进程使用，避免其中的 localhost 地址进入容器后指向错误位置。构建前需要先在平台配置可用的运行集群和镜像站推送凭据。

Compose 场景

文件 用途 对外端口 适合场景
docker-compose-dev.yaml 启动 PostgreSQL / Redis / worker 5432, 6379 默认开发联调，Vite 和 API 在宿主机跑
docker-compose.yaml 使用 DockerHub 镜像启动完整平台部署栈 8088 完整部署验收 / RC 镜像验证
docker-compose-build.yaml 从当前源码构建并启动完整平台部署栈 8088 本地镜像构建验证

常用命令：

# 开发联调：PG/Redis/worker
docker compose -f docker-compose-dev.yaml up -d --build

# 使用 DockerHub 镜像启动完整平台
docker compose up -d

# 从当前源码构建完整平台
docker compose -f docker-compose-build.yaml up -d --build

开发 compose 使用独立项目名 liteyuki-devops-dev，会占用宿主机 5432 / 6379。完整部署栈的 PostgreSQL / Redis 只在容器网络内访问，不占用宿主机数据库和缓存端口。

容器运行

使用 DockerHub 镜像启动完整平台：

docker compose up -d

默认使用 liteyukistudio/devops-api:${DEVOPS_IMAGE_TAG:-nightly} 和 liteyukistudio/devops-worker:${DEVOPS_IMAGE_TAG:-nightly}。需要验证指定版本时可以覆盖镜像 tag：

DEVOPS_IMAGE_TAG=v0.1.0-rc.1 docker compose up -d

如需从当前源码构建镜像并启动完整平台，使用：

docker compose -f docker-compose-build.yaml up -d --build

完整平台 compose 内置 PostgreSQL / Redis 只在容器网络内访问，不占用宿主机 5432 / 6379，避免和开发依赖冲突；对外只暴露 API 的 8088。API 镜像内嵌前端 SPA 静态文件，根路径和前端路由由后端 fallback 到 index.html，/api/* 和 /healthz 继续走后端接口。

发布工作流只构建 linux/amd64 容器镜像，并发布到 DockerHub：liteyukistudio/devops-api、liteyukistudio/devops-worker。devops-api 使用 Go embed 内嵌前端构建产物，不再维护独立前端 Dockerfile 或 nginx 前端镜像，也不额外发布 GitHub Release 二进制产物。推送 main / dev 时发布 nightly；推送 v* tag 时发布版本 tag；只有稳定版本 tag（如 v0.1.0）额外发布 latest。

访问前端：

http://localhost:8088

容器链路：

browser
  -> api :8080
     -> embedded SPA fallback
     -> /api/* backend routes
  -> postgres / redis

worker
  -> postgres / redis
  -> deployment cluster Kubernetes API
  -> build job pod / BuildKit

完整 compose 已内联 API / worker 运行环境变量，生产部署时可以通过宿主机环境变量覆盖密钥、域名、镜像 tag 和构建参数。Worker 构建参数示例：

BUILD_EXECUTOR_IMAGE=moby/buildkit:v0.24.0-rootless
BUILD_JOB_TIMEOUT_SECONDS=5400
BUILD_JOB_TTL_SECONDS=3600
BUILD_CACHE_ENABLED=false
BUILD_CACHE_TAG=buildcache
BUILD_NPM_REGISTRY=
BUILD_PRIVATE_EGRESS_CIDRS=
BUILD_BLOCKED_EGRESS_CIDRS=

构建 Job 不挂载宿主机 Docker socket，不默认 privileged，不持有平台 API token，并显式使用受限 ServiceAccount。Git token、Registry 凭据和构建密钥通过一次性 Kubernetes Secret 注入到 Job，Job 完成后 worker 会删除临时 Secret，Pod/Job 按 TTL 保留日志窗口。Worker 会为项目命名空间应用构建出站 NetworkPolicy；默认允许 DNS 和公开 HTTP/HTTPS，BUILD_PRIVATE_EGRESS_CIDRS 可放行内网 registry/镜像源 TCP 443，BUILD_BLOCKED_EGRESS_CIDRS 可追加禁止访问的 CIDR。

运行模式

模式 行为
APP_ENV=development 启用开发默认管理员，并由后端下发登录页开发账号提示
APP_ENV=production 禁用开发默认管理员；没有平台管理员时需访问 /bootstrap 初始化
未设置 APP_ENV 默认按生产模式处理

配置加载顺序为：先读取 .env，再根据 APP_ENV 读取 .env.development 或 .env.production，最后读取 ENV_FILE 指定的文件作为覆盖。.env.development 面向宿主机进程，.env.worker 面向 docker-compose-dev.yaml 中的 worker 容器；完整部署的 docker-compose.yaml 和 docker-compose-build.yaml 已内联 API / worker 环境变量。开发模式需要在 .env 或进程环境里显式设置 APP_ENV=development：

go run ./cmd/api
go run ./cmd/worker

需要临时覆盖时再使用：

ENV_FILE=.env.local go run ./cmd/api

生产环境必须配置稳定的 SECRET_ENCRYPTION_KEY，用于加密后台直接填写的 OIDC/Git Client Secret、Git Token、镜像站凭据等敏感值。未配置时 API/worker 会拒绝启动；本地开发需要在 .env 或进程环境里显式设置 APP_ENV=development。

目录地图

cmd/api                 API 服务入口
cmd/worker              异步任务 worker 入口
internal/               后端领域模块、配置、模型和 API
migrations/             PostgreSQL 数据库迁移
openapi/                OpenAPI 定义
web/                    Vite + React 前端
web/public/             静态资源，包含 SVG logo / favicon
docs/                   Rspress 文档站源码
docs-legacy/            产品方案、场景记录和代码健康 SOP

品牌资产

前端默认公开配置、favicon 和 README 都引用同一个 SVG 源文件；后台仍可通过站点配置覆盖 site.logoUrl 和 site.faviconUrl。

文档

推荐阅读顺序：

  1. 文档站
  2. 产品与一体化方案
  3. 代码健康检查 SOP
  4. TODO
  5. AI 开发规范

开发约定

  • 前端必须使用 pnpm。
  • Python 必须使用 uv。
  • Go 后端使用 Gin + GORM。
  • 平台构建主路径使用 Worker 调度 Kubernetes Job + BuildKit。
  • Gitea/GitHub Actions 不作为当前构建主路径。
  • 部署由平台统一执行和记录。
  • 前端所有用户可见文本必须走 i18n，不在组件中硬编码文案。

About

轻雪标准运维 Devops 平台

devops-docs.liteyuki.org

Resources

Readme
Activity
Custom properties

Stars

6 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages