开发环境

开发前准备

SyncTV 是 Rust workspace，开发时通常需要：

• Rust stable toolchain。
• PostgreSQL。
• Redis。
• Node.js 和 npm，用于 docs/ 文档站。
• Docker 和 Docker Compose，用于快速启动依赖服务。
• Protobuf/gRPC 相关构建依赖，具体取决于本机平台和 Rust crate 构建过程。

建议先确认：

rustc --version
cargo --version
docker --version
docker compose version
node --version
npm --version

仓库结构

• synctv 核心二进制和 CLI
• synctv-core 业务逻辑、配置、服务和 repository
• synctv-api HTTP/gRPC API
• synctv-livestream RTMP/HLS/HTTP-FLV
• synctv-cluster 集群协调
• synctv-proxy 媒体代理和 slice cache
• synctv-proto protobuf 定义
• 文件夹helm

  • synctv Helm chart
• docs Astro Starlight 文档站

启动开发依赖

最简单方式是使用开发 Compose：

docker compose -f docker-compose.dev.yml up -d postgres redis

如果你希望连 SyncTV 服务也一起用容器启动：

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

开发 Compose 使用仓库内 Dockerfile 构建镜像，并带有开发用 secret。它只适合本地开发，不适合生产。

本机运行服务

本机直接运行：

1. 确认依赖服务已启动：

   docker compose -f docker-compose.dev.yml up -d postgres redis

2. 校验配置：

   cargo run -p synctv --bin synctv -- config validate

3. 启动服务：

   cargo run -p synctv --bin synctv -- serve

直接运行命令：

cargo run -p synctv --bin synctv -- serve

使用指定配置文件：

cargo run -p synctv --bin synctv -- serve --config synctv.yaml

只验证配置、不真正启动：

cargo run -p synctv --bin synctv -- serve --config synctv.yaml --dry-run

配置校验

开发时修改配置结构后，先跑：

cargo run -p synctv --bin synctv -- config --config synctv.yaml validate

查看最终合并后的配置，secret 会被隐藏：

cargo run -p synctv --bin synctv -- config --config synctv.yaml show
cargo run -p synctv --bin synctv -- config --config synctv.yaml show --output json

配置来源优先级和环境变量规则见 配置文件如何工作。

数据库迁移

服务启动阶段会自动执行 embedded SQLx migrations。需要在不启动服务的情况下预检数据库状态时，可以单独执行：

cargo run -p synctv --bin synctv -- db migrate

检查数据库连接和迁移状态：

cargo run -p synctv --bin synctv -- db status

开发中如果数据库状态异常，优先检查：

• SYNCTV_DATABASE_URL 或 database.url。
• PostgreSQL 容器是否健康。
• migration 文件是否与代码期望一致。
• 当前分支是否有未应用的 schema 变更。

测试

全 workspace 测试：

cargo test --workspace --all-targets

只跑某个 crate：

cargo test -p synctv-api

只跑某个测试：

cargo test -p synctv-api test_name

格式检查：

cargo fmt --all --check

Clippy：

cargo clippy --workspace --all-targets --all-features -- -D warnings

如果修改了特定功能，优先跑对应的聚焦测试，再跑更大的测试集。不要只依赖编译通过。

SQLx offline metadata

数据库查询如果使用 SQLx macros，会在编译期检查 SQL，并把 metadata 缓存在 .sqlx/。修改 SQL、migration 或查询返回类型后需要刷新。

提示

CI 可以使用 SQLX_OFFLINE=true 编译，不需要连接真实数据库；前提是 .sqlx/ metadata 已经和代码同步。

刷新流程：

docker compose -f docker-compose.dev.yml down -v
docker compose -f docker-compose.dev.yml up -d postgres redis

SYNCTV_DATABASE_URL=postgresql://synctv:synctv@localhost:5432/synctv \
SYNCTV_JWT_SECRET=dev-jwt-secret-please-change-in-production-1234567890 \
SYNCTV_SERVER_CLUSTER_SECRET=dev-cluster-secret-please-change-in-production-1234567890 \
SYNCTV_SECURITY_CREDENTIAL_ENCRYPTION_KEY=000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f \
SYNCTV_SECURITY_OPAQUE_SERVER_SETUP_SECRET=dev-opaque-server-setup-secret-please-change-1234567890 \
cargo run -p synctv --bin synctv -- db migrate

DATABASE_URL=postgresql://synctv:synctv@localhost:5432/synctv \
cargo sqlx prepare --workspace

SQLX_OFFLINE=true cargo check --workspace --all-targets

OpenAPI 功能

内置 OpenAPI 文档由 openapi feature 启用。开发者获取方式见 OpenAPI 文档入口。

常用检查：

cargo check --workspace --all-targets --features openapi

启动带 Swagger UI 的服务：

cargo run -p synctv --features openapi --bin synctv -- serve

文档站开发

文档站在 docs/ 目录，是独立的 Astro Starlight 项目。

首次安装依赖：

cd docs
npm install

本地预览：

cd docs
npm run dev

构建：

cd docs
npm run build

如果文档站部署在域名子路径下，构建时指定 SYNCTV_DOCS_BASE。如果需要正确生成 canonical URL 和 sitemap，同时指定 SYNCTV_DOCS_SITE。

cd docs
SYNCTV_DOCS_SITE=https://example.com SYNCTV_DOCS_BASE=/synctv npm run build

SYNCTV_DOCS_BASE 只表示路径前缀，例如 /synctv、/docs。部署在域名根路径时不需要设置。

构建输出在 docs/dist，它是生成产物，不需要提交。

修改 CLI 时

CLI 定义在 synctv/src/cli.rs。修改命令或参数后至少检查：

cargo run -p synctv --bin synctv -- --help
cargo run -p synctv --bin synctv -- user --help
cargo run -p synctv --bin synctv -- provider --help

如果新增命令，也要更新 CLI 参考。

修改 Helm 或 Compose 时

Helm：

helm lint ./helm/synctv
helm template synctv ./helm/synctv
helm template synctv ./helm/synctv --set ingress.grpc.enabled=true

Compose：

docker compose -f docker-compose.dev.yml config
docker compose config

注意：渲染成功只说明 YAML 语法和模板基本可用，不代表业务配置安全。还要运行 SyncTV 配置校验或实际启动验证。