本地开发

本地开发分为后端（Go 多角色）与前端（pnpm monorepo）两部分。基础设施（PostgreSQL / Redis / MinIO / Kafka / etcd）既可以本地安装，也可以直接复用 compose 中的容器。

方案 A：复用 compose 基础设施 + 本地跑后端

这是最省事的组合：只用 Docker 起中间件，业务进程全部本地运行，方便断点调试。

# 1. 启动基础设施（postgres/redis/minio/kafka/etcd，不含业务服务）
docker compose up -d postgres redis minio kafka etcd

# 2. 本地启动各角色（新终端分别执行）
go run ./cmd/vistack api          # API 服务，默认 :8080
go run ./cmd/vistack worker       # 转码编排 Worker
go run ./cmd/vistack transcoder   # gRPC 转码服务（需本机安装 FFmpeg）
go run ./cmd/vistack auth         # Auth 服务（:8081 HTTP + :50052 gRPC）

配置注意

本地运行时默认加载 conf/app.toml，其中中间件地址为 localhost（对应 compose 映射到宿主机的端口），可直接使用。若想对齐容器内配置，可指定：

VISTACK_CONFIG_PATH=conf/app.docker.toml go run ./cmd/vistack api

（此时中间件地址为 compose 服务名，需在容器网络中运行，不建议本机直连。）

方案 B：完全本地环境

需要本机安装并启动以下组件：

组件	默认地址	说明
PostgreSQL	localhost:5432	元数据存储
Redis	localhost:6379	缓存 / 计数 / 队列
MinIO	localhost:9000（API）/ 9001（控制台）	对象存储
Kafka	localhost:9092	任务队列
etcd	localhost:2379	服务发现 / 领导选举
FFmpeg / FFprobe	任意	transcoder 角色依赖，ffmpeg -version 可验证

然后依次启动四个角色：

go run ./cmd/vistack api
go run ./cmd/vistack worker
go run ./cmd/vistack transcoder
go run ./cmd/vistack auth

角色启动方式

单二进制 + 角色分发，两种方式等价：

# 方式 1：位置参数
go run ./cmd/vistack api

# 方式 2：环境变量 VISTACK_ROLE
VISTACK_ROLE=worker go run ./cmd/vistack

支持的角色：api / worker / transcoder / auth / migrate。

角色	职责	依赖	默认端口
api	HTTP 服务：上传/预签名/视频/弹幕/评论/互动	DB + Redis + MinIO + Kafka	8080
worker	Kafka 消费：转码编排、删除、弹幕/评论落库、重试 + watchdog	DB + Redis + MinIO + Kafka + etcd	-
transcoder	gRPC 转码：MinIO 下载 → FFmpeg 转码 → 上传	MinIO + etcd（注册）	50051
auth	HTTP 认证 + gRPC 用户查询 + etcd 注册	DB + etcd	8081 / 50052
migrate	执行 GORM 自动迁移后退出	DB	-

前端

cd web
pnpm install
pnpm run dev

• 用户端 web-client：http://localhost:8335
• 管理端 web-admin：http://localhost:8334
• UI 组件库 ui：被两个前端引用

前端 API 指向

前端通过环境文件配置 API 地址（web/web-client/.env.development 与 web/web-admin/.env.development）：

VITE_API_BASE=http://localhost/api/v1

• Docker 部署场景：http://localhost/api/v1（Traefik 统一入口，自动分流 auth / api）；
• 本地直连场景：改为 http://localhost:8080/api/v1（API）与 http://localhost:8081/api/v1（Auth）时，注意 CORS 需允许对应来源（见 conf/app.toml 的 [cors]）。

数据库迁移

开发过程中如需手动执行迁移（等价于 migrate 角色）：

go run ./cmd/vistack migrate

常见调试技巧

• 查看转码任务状态：SELECT * FROM video_transcodes ORDER BY id DESC LIMIT 10;
• 查看重试队列：docker compose exec redis redis-cli ZRANGE transcode:retry:zset 0 -1 WITHSCORES
• 查看 etcd 注册节点：docker compose exec etcd etcdctl get /vistack/transcoders --prefix
• 查看 Kafka 消费情况：docker compose exec kafka kafka-consumer-groups --bootstrap-server kafka:29092 --group vistack-consumer-group --describe