快速开始
本文档带你用最短路径把 Vistack 跑起来。推荐使用 Docker Compose 一键部署（方式一），零本地依赖；想参与开发则参考方式二「本地开发」。
前置要求
- 方式一：安装 Docker 与 Docker Compose（Docker Desktop 自带）。
- 方式二：Go 1.26+、Node.js 18+、pnpm 9+，以及本地的 PostgreSQL / Redis / MinIO / Kafka / etcd（或复用 compose 中的基础设施）。
方式一：Docker Compose 一键部署（推荐）
bash
# 1. 克隆仓库
git clone https://github.com/binhy/vistack.git
cd vistack
# 2. 复制环境变量模板
cp .env.example .env.local
# 3. 一键起栈（构建镜像并后台启动全部服务）
docker compose up --build -d
# 4. 查看服务状态
docker compose ps启动完成后，全套服务即可用：
| 服务 | 地址 | 说明 |
|---|---|---|
| 统一入口（Traefik） | http://localhost/api/v1 | 按路径分流 auth 与 api |
| API 服务 | http://localhost:8080/api/v1 | 视频 / 文件业务 |
| Auth 服务 | http://localhost:8081 | 注册 / 登录 / 资料 / JWKS |
| Traefik 仪表盘 | http://localhost:8082/dashboard/ | 路由可视化 |
| MinIO 控制台 | http://localhost:9001 | 账号 minioadmin / minioadmin |
| PostgreSQL | localhost:5432 | postgres / postgres |
| Redis | localhost:6379 | 无密码 |
| Kafka | localhost:9092 | KRaft 单节点 |
| etcd | localhost:2379 | 服务注册 / 领导选举 |
验证服务健康
bash
# API 健康检查
curl http://localhost:8080/health
# 统一入口健康检查
curl http://localhost/api/v1/health水平扩容转码节点
转码是计算密集任务，需要更多并发转码能力时直接扩容：
bash
# 扩容到 3 个 transcoder 副本
docker compose up --scale transcoder=3 -d
# 查看注册到 etcd 的转码节点
docker compose exec etcd etcdctl get /vistack/transcoders --prefixworker 会通过 etcd 自动发现新增的转码节点并做 gRPC 负载均衡，无需重启。
停止 / 清理
bash
# 停止全部服务（保留数据卷）
docker compose down
# 停止并删除数据卷（彻底清理）
docker compose down -v方式二：本地开发
详见 本地开发。
前端访问
前端 monorepo 位于 web/（pnpm workspace：ui / web-client / web-admin）：
bash
cd web
pnpm install
pnpm run dev # web-client(:8335) 与 web-admin(:8334)浏览器打开：
前端通过
web/*/.env.development中的VITE_API_BASE指向 API，默认http://localhost/api/v1（即 Docker 部署时的 Traefik 统一入口）；本地纯前端开发时请确认其与后端实际监听端口一致。
常见操作示例
注册并登录（Auth 服务）
bash
# 注册
curl -X POST http://localhost:8081/api/v1/auth/register \
-H "Content-Type: application/json" \
-d '{"username":"demo","password":"demo123456","email":"demo@example.com"}'
# 登录，拿到 access_token
curl -X POST http://localhost:8081/api/v1/auth/login \
-H "Content-Type: application/json" \
-d '{"username":"demo","password":"demo123456"}'查看 JWKS（验证 Auth 无状态验签）
bash
curl http://localhost:8081/.well-known/jwks.json上传视频触发转码流水线
- 使用前端页面上传视频（分片上传 + 秒传）；
- 上传完成后 API 投递
Kafka[transcode]任务； - worker 消费任务 → etcd 发现 transcoder → gRPC
ProcessVideo远程转码； - 转码完成后视频状态变为
published，前端即可播放。
下一步
- 想了解整个系统如何协作 → 系统架构总览
- 想在生产环境部署 → Docker 一键部署详解 ｜ Kubernetes 部署