Docker Compose
仅使用容器进行本地试用时，在仓库根目录执行：
./scripts/setup-compose.sh
docker compose up --build -d --wait
访问 http://localhost:3000，邮箱 admin@localhost，密码在生成的 .env 中。此流程自动启动数据库、执行迁移并等待服务健康，数据保存在命名卷中。本地 HTTP 模板连接外部 Git 来源；托管 Git 与生产 HTTPS/OIDC 使用 deployments/preproduction/。端口、升级与数据保留见 Compose 说明。
本地启动
准备 Docker、Node 24、Git 和 Python 3。Makefile 使用 Go 1.26.10 工具链。在项目根目录执行：
cp .env.example .env.local
# 编辑 .env.local，设置独立的管理员密码（至少 14 字符）
chmod 600 .env.local
make deps
make dev
默认管理端端口 3000，API 8080，PostgreSQL 55432。若 3000 已占用，在配置中同时设置 SKIVA_WEB_PORT 和 SKIVA_WEB_ORIGIN。
生产部署检查
配置 TLS、PostgreSQL 与内容目录持久化、OIDC、Git 主机允许列表、Secret 引用和备份。迁移数据库后再启动 API / Worker。部署模板位于 deployments/compose.yaml 和 deployments/docker/。
/distribution/ 请求应直接转发到 Go 服务；/metrics 只对监控网络开放。后端镜像已完成本地构建和迁移命令验证；单机预生产模板见 deployments/preproduction/。实际域名 TLS、企业 IdP 与告警接收仍需部署环境验收。
详细安装、OIDC、SSH、备份恢复说明保存在项目 docs/OPERATIONS.md。
备份与恢复
备份需要同时包含数据库和 Git / CAS 数据目录。先停止 API / Worker 写入，再运行备份脚本，保证恢复点一致；将备份放在受保护且不位于数据目录内的位置。
# 先配置数据库连接、数据目录和备份目录
export SKIVA_BACKUP_DIR=/secure-backups/skiva
./scripts/backup.sh
恢复应使用新的空数据库和数据目录，按运维手册校验备份校验和与全部引用对象后再切换服务。不要用生产库执行测试迁移回滚。
常见问题
| 现象 | 检查顺序 |
|---|---|
| Git 连接失败 | 地址与 Ref → 允许列表 / DNS → Secret 引用 → CA 或 SSH known_hosts |
| 同步后没有新版本 | 流水线诊断 → 来源 Commit → 内容是否实际变化 → 扫描目录 |
| 构建成功但客户端未更新 | 是否创建新快照 → 是否推进正确渠道 → Profile → dynamic / pinned |
| 某个 Skill 消失 | 快照是否包含该 Skill → Profile 是否授权 |
| Blob 返回 403 | 客户端身份 → Profile → 快照授权 → 文件成员关系 |
| Blob 返回 503 | 对象是否缺失或损坏，运行完整性巡检 |
| 发布返回 409 | generation 是否已被其他发布修改，刷新并重新确认 |
| 挂载目录变了但 Agent 没变 | Agent 索引、已加载上下文、旧句柄或 pinned 模式 |
| Token 丢失 | 轮换凭据，重新登录客户端 |
验证与巡检
make test-db
make lint test build
# 配置正确的 SKIVA_DATABASE_URL 和 SKIVA_DATA_DIR 后巡检
make verify-artifacts
测试库与应用库必须分开。维护命令见项目 docs/OPERATIONS.md；验收证据和部署边界见 docs/ACCEPTANCE.md。生产 SLO、企业 IdP 与真实网络故障恢复需要部署环境验收。