mediamtx/docs/maintainer/3-architecture-and-code-map.md

generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Architecture-and-Code-Map wiki_url: https://git.ilapage.cn/OPC/mediamtx/wiki/Architecture-and-Code-Map.- wiki_revision: 2b5014fc8d752f58255ebc4318acd8d798bc29be synchronized_at: 2026-08-28T08:45:08Z

架构与代码地图

上游入口

• main.go：程序入口。
• internal/core/：服务装配、配置重载和生命周期。
• internal/api/：Control API，当前版本使用 /v3 路由。
• internal/conf/：配置结构、默认值与校验。
• internal/servers/webrtc/：WebRTC/WHEP 服务及内置原生播放页面。
• internal/servers/hls/：HLS 服务。
• mediamtx.yml：完整配置参考。
• api/openapi.yaml：Control API 契约。
• internal/**/*_test.go：单元和集成测试。

内嵌管理页面

MediaMTX API HTTP 服务 :9997
├─ /admin                         301 规范化到 /admin/
├─ /admin/                        匿名加载内嵌登录外壳与 index.html
├─ /admin/app.css                 内嵌原生样式
├─ /admin/app.js                  内嵌原生交互
├─ /admin/list-tools.js           分批读取、完整集合与客户端分页工具
└─ /v3/...                        action: api 强制认证的 Control API

MediaMTX WebRTC :8889/{path}       内置页面负责低延迟预览
MediaMTX HLS    :8888/{path}/      内置页面负责兼容预览

管理页面只调用既有 Control API、展示状态并在 iframe 中打开 MediaMTX 内置播放器，不代理 RTSP 或 HTTP 媒体数据，不引入 Node、数据库或前端框架。

代码边界

• internal/api/api.go：匿名提供 /admin 与 /admin/*path 静态资源，仅在 /v3 路由组应用 API 认证中间件。
• internal/api/api_admin.go：Go embed、资源响应、缓存策略和安全响应头。
• internal/api/admin/index.html：语义化登录页、管理页、表单、对话框与无障碍 live regions。
• internal/api/admin/app.css：蓝灰设计 token、桌面表格、375px 卡片布局、焦点与 reduced-motion。
• internal/api/admin/app.js：Basic 登录、当前标签页会话、401 清理、退出，以及全量分批加载、配置/状态合并、CRUD、脱敏、筛选、客户端分页和预览。
• internal/api/admin/list-tools.js：无运行时依赖的列表工具，负责共享并发上限、API 多页完整读取、稳定去重排序、完整统计和分页钳制；Node 测试可直接加载。
• internal/api/api_admin_test.go：入口、重定向、资源、CSP、鉴权和静态安全约束测试。

主要 API

• GET /v3/config/global/get
• GET /v3/config/paths/list
• POST /v3/config/paths/add/{name}
• PATCH /v3/config/paths/patch/{name}
• DELETE /v3/config/paths/delete/{name}
• GET /v3/paths/list

API 契约以当前仓库 api/openapi.yaml 为唯一代码级事实来源。

修改边界

• 不改变 RTSP 拉流、转封装、协议协商等媒体核心行为。
• 管理静态资源只负责展示登录外壳；所有管理数据和写操作仍复用 /v3 的 action: api 认证边界。
• 预览复用上游内置 WebRTC/HLS 页面，避免维护第二套媒体播放实现。
• 前端只保留管理静态 RTSP 源需要的最小配置字段；新增字段必须按工单和 API 契约扩展。
• 列表 API 固定以每页 100 条分批读取，配置与运行状态请求共用最多 4 个并发槽；完整快照成功后才替换页面数据，再执行统计、筛选和客户端分页。