2026-08-15 08:42:05 +08:00
20 changed files with 1381 additions and 8 deletions
@@ -0,0 +1,27 @@
+package router
+
+import (
+	"git.ilapage.cn/ila/yovision/Sense/server/app/sense/liveview"
+	"git.ilapage.cn/ila/yovision/Sense/server/common/actions"
+	"git.ilapage.cn/ila/yovision/Sense/server/common/middleware"
+	"github.com/gin-gonic/gin"
+	jwt "github.com/go-admin-team/go-admin-core/sdk/pkg/jwtauth"
+)
+
+func init() {
+	routerCheckRole = append(routerCheckRole, registerSenseLiveviewRouter)
+	routerNoCheckRole = append(routerNoCheckRole, registerSenseLiveviewPlayerRouter)
+}
+
+func registerSenseLiveviewRouter(v1 *gin.RouterGroup, auth *jwt.GinJWTMiddleware) {
+	api := &liveview.API{}
+	r := v1.Group("/liveview").Use(auth.MiddlewareFunc()).Use(middleware.AuthCheckRole()).Use(actions.PermissionAction())
+	r.GET("/routes", api.List)
+	r.POST("/sessions", api.Create)
+	r.GET("/sessions/:id", api.Get)
+}
+
+func registerSenseLiveviewPlayerRouter(v1 *gin.RouterGroup) {
+	api := &liveview.API{}
+	v1.GET("/liveview/player/:id", api.Player)
+}
@@ -0,0 +1,134 @@
+package liveview
+
+import (
+	"encoding/json"
+	"errors"
+	"html/template"
+	"io"
+	"net/http"
+	"strconv"
+	"strings"
+
+	"github.com/gin-gonic/gin"
+	"github.com/go-admin-team/go-admin-core/sdk/api"
+	"github.com/go-admin-team/go-admin-core/sdk/pkg/jwtauth/user"
+	coreService "github.com/go-admin-team/go-admin-core/sdk/service"
+)
+
+type API struct{ api.Api }
+
+func (e *API) service(c *gin.Context) (*Service, error) {
+	base := coreService.Service{}
+	if err := e.MakeContext(c).MakeOrm().MakeService(&base).Errors; err != nil {
+		return nil, err
+	}
+	return NewService(base.Orm, nil), nil
+}
+
+func (e *API) List(c *gin.Context) {
+	service, err := e.service(c)
+	if err != nil {
+		e.Error(http.StatusInternalServerError, err, "实时监看服务初始化失败")
+		return
+	}
+	pageIndex, _ := strconv.Atoi(c.DefaultQuery("pageIndex", "1"))
+	pageSize, _ := strconv.Atoi(c.DefaultQuery("pageSize", "10"))
+	items, total, err := service.List(c.Request.Context(), PageRequest{Keyword: c.Query("keyword"), PageIndex: pageIndex, PageSize: pageSize})
+	if err != nil {
+		e.writeError(err)
+		return
+	}
+	e.PageOK(items, int(total), pageIndex, pageSize, "查询成功")
+}
+
+func (e *API) Create(c *gin.Context) {
+	service, err := e.service(c)
+	if err != nil {
+		e.Error(http.StatusInternalServerError, err, "实时监看服务初始化失败")
+		return
+	}
+	var request struct {
+		RouteID string `json:"routeId"`
+	}
+	if err = decodeJSON(c, &request); err != nil {
+		e.Error(http.StatusBadRequest, err, "请求内容格式不正确")
+		return
+	}
+	session, err := service.Create(c.Request.Context(), user.GetUserId(c), request.RouteID, c.Request)
+	if err != nil {
+		e.writeError(err)
+		return
+	}
+	e.OK(session, "播放会话已创建")
+}
+
+func (e *API) Get(c *gin.Context) {
+	service, err := e.service(c)
+	if err != nil {
+		e.Error(http.StatusInternalServerError, err, "实时监看服务初始化失败")
+		return
+	}
+	session, err := service.Get(c.Request.Context(), user.GetUserId(c), c.Param("id"))
+	if err != nil {
+		e.writeError(err)
+		return
+	}
+	e.OK(session, "查询成功")
+}
+
+var playerTemplate = template.Must(template.New("liveview-player").Parse(`<!doctype html>
+<html lang="zh-CN"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<style>html,body,iframe{width:100%;height:100%;margin:0;border:0;background:#101419;overflow:hidden}</style></head>
+<body><iframe src="{{.}}" title="Sense 实时视频" allow="autoplay; fullscreen" referrerpolicy="no-referrer"></iframe></body></html>`))
+
+func (e *API) Player(c *gin.Context) {
+	target, err := NewService(nil, nil).PlayerTarget(c.Param("id"))
+	if err != nil {
+		c.Header("Cache-Control", "no-store")
+		c.String(http.StatusGone, "播放会话已过期，请重新连接")
+		return
+	}
+	parsed := template.URL(target)
+	c.Header("Content-Type", "text/html; charset=utf-8")
+	c.Header("Cache-Control", "no-store")
+	c.Header("Referrer-Policy", "no-referrer")
+	c.Header("X-Content-Type-Options", "nosniff")
+	c.Header("X-Frame-Options", "SAMEORIGIN")
+	c.Header("Content-Security-Policy", "default-src 'none'; frame-ancestors 'self'; frame-src http: https:; style-src 'unsafe-inline'")
+	if err = playerTemplate.Execute(c.Writer, parsed); err != nil {
+		c.AbortWithStatus(http.StatusInternalServerError)
+	}
+}
+
+func (e *API) writeError(err error) {
+	switch {
+	case errors.Is(err, ErrInvalidRequest):
+		e.Error(http.StatusBadRequest, err, err.Error())
+	case errors.Is(err, ErrRouteNotFound):
+		e.Error(http.StatusNotFound, err, err.Error())
+	case errors.Is(err, ErrSessionExpired):
+		e.Error(http.StatusGone, err, "播放会话已过期，请重新连接")
+	case strings.Contains(err.Error(), "WEBRTC_PUBLIC_BASE"), strings.Contains(err.Error(), "浏览器可访问"):
+		e.Error(http.StatusServiceUnavailable, err, "浏览器播放地址未正确配置")
+	default:
+		e.Error(http.StatusInternalServerError, err, "实时监看操作失败")
+	}
+}
+
+func decodeJSON(c *gin.Context, target any) error {
+	if !strings.HasPrefix(strings.ToLower(strings.TrimSpace(c.GetHeader("Content-Type"))), "application/json") {
+		return errors.New("content type must be application/json")
+	}
+	decoder := json.NewDecoder(http.MaxBytesReader(c.Writer, c.Request.Body, 16<<10))
+	decoder.DisallowUnknownFields()
+	if err := decoder.Decode(target); err != nil {
+		return err
+	}
+	if err := decoder.Decode(&struct{}{}); !errors.Is(err, io.EOF) {
+		if err == nil {
+			return errors.New("request body must contain one JSON object")
+		}
+		return err
+	}
+	return nil
+}
@@ -0,0 +1,41 @@
+package liveview
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/gin-gonic/gin"
+)
+
+func TestPlayerUsesShortLivedCapabilityAndRestrictiveHeaders(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	store := NewStore()
+	now := time.Date(2026, 8, 14, 10, 0, 0, 0, time.UTC)
+	store.now = func() time.Time { return now }
+	previous := defaultStore
+	defaultStore = store
+	t.Cleanup(func() { defaultStore = previous })
+	store.put(sessionRecord{ID: "view_test", OwnerID: 7, RouteID: "route-1", TargetURL: "http://127.0.0.1:8889/sense_test?controls=true", ExpiresAt: now.Add(sessionTTL)})
+
+	router := gin.New()
+	api := &API{}
+	router.GET("/api/v1/liveview/player/:id", api.Player)
+	recorder := httptest.NewRecorder()
+	router.ServeHTTP(recorder, httptest.NewRequest(http.MethodGet, "/api/v1/liveview/player/view_test", nil))
+	if recorder.Code != http.StatusOK || recorder.Header().Get("Cache-Control") != "no-store" || recorder.Header().Get("X-Frame-Options") != "SAMEORIGIN" {
+		t.Fatalf("status=%d headers=%v", recorder.Code, recorder.Header())
+	}
+	if !strings.Contains(recorder.Body.String(), "http://127.0.0.1:8889/sense_test?controls=true") || !strings.Contains(recorder.Header().Get("Content-Security-Policy"), "frame-ancestors 'self'") {
+		t.Fatalf("unexpected wrapper response: %s", recorder.Body.String())
+	}
+
+	now = now.Add(sessionTTL)
+	expired := httptest.NewRecorder()
+	router.ServeHTTP(expired, httptest.NewRequest(http.MethodGet, "/api/v1/liveview/player/view_test", nil))
+	if expired.Code != http.StatusGone {
+		t.Fatalf("expired capability status=%d", expired.Code)
+	}
+}
@@ -0,0 +1,291 @@
+package liveview
+
+import (
+	"context"
+	"crypto/rand"
+	"encoding/hex"
+	"errors"
+	"fmt"
+	"net"
+	"net/http"
+	"net/url"
+	"os"
+	"regexp"
+	"strings"
+	"sync"
+	"time"
+
+	"gorm.io/gorm"
+)
+
+var (
+	ErrInvalidRequest = errors.New("实时监看请求不符合要求")
+	ErrRouteNotFound  = errors.New("可监看的视频不存在")
+	ErrSessionExpired = errors.New("播放会话已过期")
+	validMediaPath    = regexp.MustCompile(`^[A-Za-z0-9_-]{1,96}$`)
+	validDNSHost      = regexp.MustCompile(`^[A-Za-z0-9.-]+$`)
+)
+
+const sessionTTL = 2 * time.Minute
+
+type PageRequest struct {
+	Keyword   string
+	PageIndex int
+	PageSize  int
+}
+
+type RouteResponse struct {
+	ID             string `json:"id"`
+	DeviceID       string `json:"deviceId"`
+	DeviceName     string `json:"deviceName"`
+	DeviceLocation string `json:"deviceLocation"`
+	ProfileToken   string `json:"profileToken"`
+	ProfileName    string `json:"profileName"`
+	ProfileKind    string `json:"profileKind"`
+	Width          int    `json:"width"`
+	Height         int    `json:"height"`
+	Encoding       string `json:"encoding"`
+	Actual         string `json:"actual"`
+	Detail         string `json:"detail"`
+	Readers        int    `json:"readers"`
+}
+
+type SessionResponse struct {
+	ID          string    `json:"id"`
+	RouteID     string    `json:"routeId"`
+	PlayerURL   string    `json:"playerUrl"`
+	Status      string    `json:"status"`
+	Detail      string    `json:"detail"`
+	ExpiresAt   time.Time `json:"expiresAt"`
+	DeviceName  string    `json:"deviceName"`
+	ProfileName string    `json:"profileName"`
+}
+
+type routeRecord struct {
+	RouteResponse
+	Path    string `gorm:"column:path"`
+	Desired string `gorm:"column:desired"`
+}
+
+type sessionRecord struct {
+	ID          string
+	OwnerID     int
+	RouteID     string
+	TargetURL   string
+	ExpiresAt   time.Time
+	DeviceName  string
+	ProfileName string
+}
+
+type Store struct {
+	mu       sync.RWMutex
+	sessions map[string]sessionRecord
+	now      func() time.Time
+}
+
+func NewStore() *Store {
+	return &Store{sessions: make(map[string]sessionRecord), now: time.Now}
+}
+
+var defaultStore = NewStore()
+
+type Service struct {
+	db    *gorm.DB
+	store *Store
+}
+
+func NewService(db *gorm.DB, store *Store) *Service {
+	if store == nil {
+		store = defaultStore
+	}
+	return &Service{db: db, store: store}
+}
+
+func (s *Service) List(ctx context.Context, request PageRequest) ([]RouteResponse, int64, error) {
+	if request.PageIndex < 1 {
+		request.PageIndex = 1
+	}
+	if request.PageSize < 1 {
+		request.PageSize = 10
+	}
+	if request.PageSize > 50 {
+		request.PageSize = 50
+	}
+	query := s.routeQuery(ctx).Where("r.desired = ?", "running")
+	keyword := strings.TrimSpace(request.Keyword)
+	if len([]rune(keyword)) > 128 {
+		return nil, 0, ErrInvalidRequest
+	}
+	if keyword != "" {
+		pattern := "%" + escapeLike(keyword) + "%"
+		query = query.Where("LOWER(d.name) LIKE LOWER(?) ESCAPE '\\' OR LOWER(d.location) LIKE LOWER(?) ESCAPE '\\' OR LOWER(p.name) LIKE LOWER(?) ESCAPE '\\'", pattern, pattern, pattern)
+	}
+	var total int64
+	if err := query.Count(&total).Error; err != nil {
+		return nil, 0, err
+	}
+	var records []routeRecord
+	if err := query.Order("d.name ASC, p.kind ASC, p.width DESC").Offset((request.PageIndex - 1) * request.PageSize).Limit(request.PageSize).Scan(&records).Error; err != nil {
+		return nil, 0, err
+	}
+	items := make([]RouteResponse, 0, len(records))
+	for _, record := range records {
+		items = append(items, record.RouteResponse)
+	}
+	return items, total, nil
+}
+
+func (s *Service) Create(ctx context.Context, ownerID int, routeID string, request *http.Request) (SessionResponse, error) {
+	if ownerID < 1 || strings.TrimSpace(routeID) == "" {
+		return SessionResponse{}, ErrInvalidRequest
+	}
+	record, err := s.route(ctx, routeID)
+	if err != nil {
+		return SessionResponse{}, err
+	}
+	if record.Desired != "running" || !validMediaPath.MatchString(record.Path) {
+		return SessionResponse{}, ErrRouteNotFound
+	}
+	base, err := playbackBase(request)
+	if err != nil {
+		return SessionResponse{}, err
+	}
+	target := *base
+	target.Path = strings.TrimRight(target.Path, "/") + "/" + record.Path
+	target.RawQuery = "controls=true&muted=true&autoplay=true"
+	id, err := randomID()
+	if err != nil {
+		return SessionResponse{}, err
+	}
+	now := s.store.now().UTC()
+	session := sessionRecord{ID: id, OwnerID: ownerID, RouteID: record.ID, TargetURL: target.String(), ExpiresAt: now.Add(sessionTTL), DeviceName: record.DeviceName, ProfileName: record.ProfileName}
+	s.store.put(session)
+	return responseFrom(session, record), nil
+}
+
+func (s *Service) Get(ctx context.Context, ownerID int, id string) (SessionResponse, error) {
+	session, err := s.store.get(id, ownerID, true)
+	if err != nil {
+		return SessionResponse{}, err
+	}
+	record, err := s.route(ctx, session.RouteID)
+	if err != nil || record.Desired != "running" {
+		return SessionResponse{}, ErrRouteNotFound
+	}
+	session.ExpiresAt = s.store.now().UTC().Add(sessionTTL)
+	s.store.put(session)
+	return responseFrom(session, record), nil
+}
+
+func (s *Service) PlayerTarget(id string) (string, error) {
+	session, err := s.store.get(id, 0, false)
+	if err != nil {
+		return "", err
+	}
+	return session.TargetURL, nil
+}
+
+func (s *Service) route(ctx context.Context, id string) (routeRecord, error) {
+	var record routeRecord
+	if err := s.routeQuery(ctx).Where("r.id = ?", id).Limit(1).Scan(&record).Error; err != nil {
+		return routeRecord{}, err
+	}
+	if record.ID == "" {
+		return routeRecord{}, ErrRouteNotFound
+	}
+	return record, nil
+}
+
+func (s *Service) routeQuery(ctx context.Context) *gorm.DB {
+	return s.db.WithContext(ctx).Table("sense_media_routes AS r").
+		Select("r.id, r.device_id, d.name AS device_name, d.location AS device_location, r.profile_token, p.name AS profile_name, p.kind AS profile_kind, p.width, p.height, p.encoding, r.actual, r.detail, r.readers, r.path, r.desired").
+		Joins("JOIN sense_devices AS d ON d.id = r.device_id").
+		Joins("JOIN sense_admission_profiles AS p ON p.device_id = r.device_id AND p.token = r.profile_token").
+		Where("d.status <> ? AND p.verification_status = ?", "disabled", "ready")
+}
+
+func responseFrom(session sessionRecord, route routeRecord) SessionResponse {
+	return SessionResponse{ID: session.ID, RouteID: session.RouteID, PlayerURL: "/api/v1/liveview/player/" + session.ID, Status: playbackStatus(route.Actual), Detail: route.Detail, ExpiresAt: session.ExpiresAt, DeviceName: session.DeviceName, ProfileName: session.ProfileName}
+}
+
+func playbackStatus(actual string) string {
+	switch actual {
+	case "ready", "waiting", "stopped":
+		return actual
+	case "credential_unavailable", "profile_unavailable":
+		return "authentication_failed"
+	case "path_missing", "apply_failed", "status_unavailable":
+		return "stream_not_found"
+	case "process_unavailable":
+		return "service_unavailable"
+	default:
+		return "offline"
+	}
+}
+
+func (s *Store) put(session sessionRecord) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	now := s.now()
+	for id, item := range s.sessions {
+		if !now.Before(item.ExpiresAt) || item.OwnerID == session.OwnerID {
+			delete(s.sessions, id)
+		}
+	}
+	s.sessions[session.ID] = session
+}
+
+func (s *Store) get(id string, ownerID int, checkOwner bool) (sessionRecord, error) {
+	s.mu.RLock()
+	session, ok := s.sessions[id]
+	s.mu.RUnlock()
+	if !ok || !s.now().Before(session.ExpiresAt) || (checkOwner && session.OwnerID != ownerID) {
+		return sessionRecord{}, ErrSessionExpired
+	}
+	return session, nil
+}
+
+func playbackBase(request *http.Request) (*url.URL, error) {
+	configured := strings.TrimSpace(os.Getenv("SENSE_MEDIAMTX_WEBRTC_PUBLIC_BASE"))
+	if configured != "" {
+		return validatePlaybackBase(configured)
+	}
+	if request == nil || request.Host == "" {
+		return nil, errors.New("无法确定浏览器可访问的视频服务地址")
+	}
+	host := request.Host
+	if parsedHost, _, err := net.SplitHostPort(request.Host); err == nil {
+		host = parsedHost
+	}
+	host = strings.Trim(host, "[]")
+	if host == "" || (net.ParseIP(host) == nil && host != "localhost" && !validDNSHost.MatchString(host)) {
+		return nil, errors.New("无效的请求主机")
+	}
+	scheme := "http"
+	if request.TLS != nil {
+		scheme = "https"
+	}
+	return validatePlaybackBase(fmt.Sprintf("%s://%s", scheme, net.JoinHostPort(host, "8889")))
+}
+
+func validatePlaybackBase(value string) (*url.URL, error) {
+	parsed, err := url.Parse(strings.TrimRight(value, "/"))
+	if err != nil || (parsed.Scheme != "http" && parsed.Scheme != "https") || parsed.Hostname() == "" || parsed.User != nil || parsed.RawQuery != "" || parsed.Fragment != "" || (parsed.Path != "" && parsed.Path != "/") {
+		return nil, errors.New("SENSE_MEDIAMTX_WEBRTC_PUBLIC_BASE 配置不安全")
+	}
+	return parsed, nil
+}
+
+func randomID() (string, error) {
+	value := make([]byte, 24)
+	if _, err := rand.Read(value); err != nil {
+		return "", err
+	}
+	return "view_" + hex.EncodeToString(value), nil
+}
+
+func escapeLike(value string) string {
+	value = strings.ReplaceAll(value, `\`, `\\`)
+	value = strings.ReplaceAll(value, `%`, `\%`)
+	return strings.ReplaceAll(value, `_`, `\_`)
+}
@@ -0,0 +1,89 @@
+package liveview
+
+import (
+	"context"
+	"encoding/json"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+
+	"gorm.io/driver/sqlite"
+	"gorm.io/gorm"
+)
+
+func testDB(t *testing.T) *gorm.DB {
+	t.Helper()
+	db, err := gorm.Open(sqlite.Open("file:"+t.Name()+"?mode=memory&cache=shared"), &gorm.Config{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	statements := []string{
+		`CREATE TABLE sense_devices (id text primary key, name text, location text, status text)`,
+		`CREATE TABLE sense_admission_profiles (device_id text, token text, name text, kind text, width integer, height integer, encoding text, verification_status text, stream_uri text)`,
+		`CREATE TABLE sense_media_routes (id text primary key, device_id text, profile_token text, path text, desired text, actual text, detail text, readers integer)`,
+		`INSERT INTO sense_devices VALUES ('device-1','东门摄像机','教学楼东门','active')`,
+		`INSERT INTO sense_admission_profiles VALUES ('device-1','main','主码流','main',1920,1080,'H264','ready','rtsp://camera.example/live')`,
+		`INSERT INTO sense_media_routes VALUES ('device-1:main','device-1','main','sense_012345','running','waiting','等待播放器连接并按需拉流',0)`,
+	}
+	for _, statement := range statements {
+		if err = db.Exec(statement).Error; err != nil {
+			t.Fatal(err)
+		}
+	}
+	return db
+}
+
+func TestListIsPaginatedSearchableAndSecretFree(t *testing.T) {
+	service := NewService(testDB(t), NewStore())
+	items, total, err := service.List(context.Background(), PageRequest{Keyword: "东门", PageIndex: 1, PageSize: 10})
+	if err != nil || total != 1 || len(items) != 1 || items[0].ProfileKind != "main" {
+		t.Fatalf("items=%+v total=%d err=%v", items, total, err)
+	}
+	encoded, _ := json.Marshal(items)
+	if strings.Contains(string(encoded), "rtsp://") || strings.Contains(string(encoded), "sense_012345") {
+		t.Fatalf("response leaked private media data: %s", encoded)
+	}
+}
+
+func TestSessionIsOwnerBoundShortLivedAndUsesBrowserHost(t *testing.T) {
+	store := NewStore()
+	now := time.Date(2026, 8, 14, 10, 0, 0, 0, time.UTC)
+	store.now = func() time.Time { return now }
+	service := NewService(testDB(t), store)
+	request := httptest.NewRequest("POST", "http://192.0.2.20:18080/api/v1/liveview/sessions", nil)
+	session, err := service.Create(context.Background(), 7, "device-1:main", request)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.HasPrefix(session.PlayerURL, "/api/v1/liveview/player/view_") || strings.Contains(session.PlayerURL, "sense_012345") {
+		t.Fatalf("unsafe player URL: %s", session.PlayerURL)
+	}
+	if _, err = service.Get(context.Background(), 8, session.ID); !errorsIs(err, ErrSessionExpired) {
+		t.Fatalf("another owner accessed session: %v", err)
+	}
+	target, err := service.PlayerTarget(session.ID)
+	if err != nil || target != "http://192.0.2.20:8889/sense_012345?controls=true&muted=true&autoplay=true" {
+		t.Fatalf("target=%q err=%v", target, err)
+	}
+	now = now.Add(sessionTTL)
+	if _, err = service.PlayerTarget(session.ID); !errorsIs(err, ErrSessionExpired) {
+		t.Fatalf("expired session remained valid: %v", err)
+	}
+}
+
+func TestPlaybackBaseRejectsCredentials(t *testing.T) {
+	if _, err := validatePlaybackBase("http://invalid-user@127.0.0.1:8889"); err == nil {
+		t.Fatal("expected credential-bearing base URL to be rejected")
+	}
+}
+
+func TestPlaybackStatusKeepsActionableFailuresDistinct(t *testing.T) {
+	for input, want := range map[string]string{"waiting": "waiting", "credential_unavailable": "authentication_failed", "path_missing": "stream_not_found", "process_unavailable": "service_unavailable", "unexpected": "offline"} {
+		if got := playbackStatus(input); got != want {
+			t.Fatalf("playbackStatus(%q)=%q want %q", input, got, want)
+		}
+	}
+}
+
+func errorsIs(err, target error) bool { return err == target }
@@ -0,0 +1,37 @@
+package version
+
+import (
+	"runtime"
+
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+
+	"git.ilapage.cn/ila/yovision/Sense/server/cmd/migrate/migration"
+	migrationModels "git.ilapage.cn/ila/yovision/Sense/server/cmd/migrate/migration/models"
+	common "git.ilapage.cn/ila/yovision/Sense/server/common/models"
+)
+
+func init() {
+	_, fileName, _, _ := runtime.Caller(0)
+	migration.Migrate.SetVersion(migration.GetFilename(fileName), migrateSenseLiveview)
+}
+
+func migrateSenseLiveview(db *gorm.DB, version string) error {
+	return db.Transaction(func(tx *gorm.DB) error {
+		page, err := ensureDeviceMenu(tx, migrationModels.SysMenu{MenuName: "SenseLiveview", Title: "实时监看", Icon: "eye-open", Path: "/sense/liveview", MenuType: "C", Permission: "sense:liveview:view", Component: "/sense/liveview/index", Sort: 8, Visible: "0", IsFrame: "1"})
+		if err != nil {
+			return err
+		}
+		for _, role := range []string{"implementation_operator", "site_admin", "viewer"} {
+			if err = attachDeviceRole(tx, role, []migrationModels.SysMenu{page}); err != nil {
+				return err
+			}
+			for _, policy := range [][2]string{{"/api/v1/liveview/routes", "GET"}, {"/api/v1/liveview/sessions", "POST"}, {"/api/v1/liveview/sessions/:id", "GET"}} {
+				if err = tx.Clauses(clause.OnConflict{DoNothing: true}).Create(&deviceCasbinRule{Ptype: "p", V0: role, V1: policy[0], V2: policy[1]}).Error; err != nil {
+					return err
+				}
+			}
+		}
+		return tx.Create(&common.Migration{Version: version}).Error
+	})
+}
@@ -0,0 +1,57 @@
+package version
+
+import (
+	"os"
+	"testing"
+
+	"gorm.io/driver/postgres"
+	"gorm.io/gorm"
+
+	migrationModels "git.ilapage.cn/ila/yovision/Sense/server/cmd/migrate/migration/models"
+	common "git.ilapage.cn/ila/yovision/Sense/server/common/models"
+)
+
+func TestLiveviewMigrationOnPostgres(t *testing.T) {
+	dsn := os.Getenv("SENSE_LIVEVIEW_MIGRATION_TEST_DATABASE_URL")
+	if dsn == "" {
+		t.Skip("set SENSE_LIVEVIEW_MIGRATION_TEST_DATABASE_URL to run the PostgreSQL migration test")
+	}
+	db, err := gorm.Open(postgres.Open(dsn), &gorm.Config{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	const schema = "sense_liveview_68_test"
+	if err = db.Exec("DROP SCHEMA IF EXISTS " + schema + " CASCADE").Error; err != nil {
+		t.Fatal(err)
+	}
+	if err = db.Exec("CREATE SCHEMA " + schema).Error; err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { db.Exec("DROP SCHEMA IF EXISTS " + schema + " CASCADE") })
+	sqlDB, err := db.DB()
+	if err != nil {
+		t.Fatal(err)
+	}
+	sqlDB.SetMaxOpenConns(1)
+	if err = db.Exec("SET search_path TO " + schema).Error; err != nil {
+		t.Fatal(err)
+	}
+	if err = db.AutoMigrate(&migrationModels.SysRole{}, &migrationModels.SysMenu{}, &deviceCasbinRule{}, &common.Migration{}); err != nil {
+		t.Fatal(err)
+	}
+	for _, role := range []string{"implementation_operator", "site_admin", "viewer"} {
+		if err = db.Create(&migrationModels.SysRole{RoleName: role, RoleKey: role, Status: "2"}).Error; err != nil {
+			t.Fatal(err)
+		}
+	}
+	if err = migrateSenseLiveview(db, "2026081420000_liveview.go"); err != nil {
+		t.Fatal(err)
+	}
+	var menus, policies, applied int64
+	db.Model(&migrationModels.SysMenu{}).Where("menu_name = ?", "SenseLiveview").Count(&menus)
+	db.Model(&deviceCasbinRule{}).Where("v1 LIKE ?", "/api/v1/liveview%").Count(&policies)
+	db.Model(&common.Migration{}).Where("version = ?", "2026081420000_liveview.go").Count(&applied)
+	if menus != 1 || policies != 9 || applied != 1 {
+		t.Fatalf("menus=%d policies=%d applied=%d", menus, policies, applied)
+	}
+}
@@ -0,0 +1,13 @@
+import request from '@/utils/request'
+
+export function listLiveviewRoutes(query) {
+  return request({ url: '/api/v1/liveview/routes', method: 'get', params: query })
+}
+
+export function createLiveviewSession(routeId) {
+  return request({ url: '/api/v1/liveview/sessions', method: 'post', data: { routeId }})
+}
+
+export function getLiveviewSession(id) {
+  return request({ url: `/api/v1/liveview/sessions/${id}`, method: 'get' })
+}
@@ -0,0 +1,126 @@
+<template>
+  <div class="sense-video-player" :aria-busy="busy ? 'true' : 'false'">
+    <iframe
+      v-if="playerUrl && playable"
+      :key="playerUrl"
+      class="sense-video-player__frame"
+      :src="playerUrl"
+      title="Sense 单路实时视频"
+      allow="autoplay; fullscreen"
+      sandbox="allow-scripts allow-same-origin allow-forms"
+      referrerpolicy="no-referrer"
+      @load="$emit('loaded')"
+    />
+    <div v-if="state !== 'ready'" class="sense-video-player__state" :class="{ 'is-overlay': playerUrl && playable }" aria-live="polite">
+      <el-icon v-if="busy" class="is-loading sense-video-player__icon" aria-hidden="true"><Loading /></el-icon>
+      <el-icon v-else class="sense-video-player__icon" aria-hidden="true"><WarningFilled /></el-icon>
+      <strong>{{ title }}</strong>
+      <span>{{ message }}</span>
+      <el-button v-if="recoverable" type="primary" :loading="retrying" @click="$emit('retry')">重新连接</el-button>
+    </div>
+  </div>
+</template>
+
+<script>
+import { playbackStatusDetail, playbackStatusLabel } from '@/views/sense/liveview/playbackStatus'
+import { Loading, WarningFilled } from '@element-plus/icons-vue'
+
+export default {
+  name: 'SenseVideoPlayer',
+  components: { Loading, WarningFilled },
+  props: {
+    state: { type: String, default: 'loading' },
+    detail: { type: String, default: '' },
+    playerUrl: { type: String, default: '' },
+    retrying: { type: Boolean, default: false }
+  },
+  emits: ['retry', 'loaded'],
+  computed: {
+    busy() {
+      return this.state === 'loading' || this.state === 'waiting'
+    },
+    playable() {
+      return ['loading', 'waiting', 'ready'].includes(this.state)
+    },
+    recoverable() {
+      return !this.busy && this.state !== 'ready'
+    },
+    title() {
+      return playbackStatusLabel(this.state)
+    },
+    message() {
+      return playbackStatusDetail(this.state, this.detail)
+    }
+  }
+}
+</script>
+
+<style scoped>
+.sense-video-player {
+  position: relative;
+  width: 100%;
+  aspect-ratio: 16 / 9;
+  min-height: 280px;
+  overflow: hidden;
+  border-radius: var(--el-border-radius-base);
+  background: #101419;
+}
+
+.sense-video-player__frame {
+  width: 100%;
+  height: 100%;
+  border: 0;
+}
+
+.sense-video-player__state {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 12px;
+  padding: 24px;
+  color: #dcdfe6;
+  text-align: center;
+  background: #101419;
+}
+
+.sense-video-player__state.is-overlay {
+  pointer-events: none;
+  background: rgb(16 20 25 / 78%);
+}
+
+.sense-video-player__state strong {
+  color: #fff;
+  font-size: 18px;
+  line-height: 1.5;
+}
+
+.sense-video-player__state span {
+  max-width: 640px;
+  font-size: 14px;
+  line-height: 1.6;
+}
+
+.sense-video-player__state .el-button {
+  pointer-events: auto;
+  min-height: 40px;
+}
+
+.sense-video-player__icon {
+  font-size: 36px;
+}
+
+@media (max-width: 767px) {
+  .sense-video-player {
+    min-height: 210px;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .sense-video-player__icon {
+    animation: none;
+  }
+}
+</style>
@@ -0,0 +1,283 @@
+<template>
+  <BasicLayout>
+    <template #wrapper>
+      <el-card class="box-card">
+        <div class="page-header">
+          <div>
+            <h3>实时监看</h3>
+            <p>按设备选择一路已验证视频；关闭窗口后不会继续占用播放器连接。</p>
+          </div>
+        </div>
+
+        <el-form ref="queryForm" :model="queryParams" inline label-position="left" class="search-form" @submit.prevent>
+          <el-form-item label="设备或位置" prop="keyword">
+            <el-input v-model.trim="queryParams.keyword" clearable placeholder="输入设备、位置或码流名称" @keyup.enter="handleQuery" />
+          </el-form-item>
+          <el-form-item>
+            <el-button type="primary" :loading="loading" @click="handleQuery">搜索</el-button>
+            <el-button @click="resetQuery">重置</el-button>
+          </el-form-item>
+        </el-form>
+
+        <el-alert
+          v-if="!loading && total === 0"
+          title="没有可监看的视频。请先在“视频接入”完成验证，再到“视频服务”确认路径状态。"
+          type="info"
+          :closable="false"
+          show-icon
+          class="empty-alert"
+        />
+
+        <el-table v-loading="loading" :data="routes" border stripe>
+          <el-table-column prop="deviceName" label="设备" min-width="160" show-overflow-tooltip />
+          <el-table-column prop="deviceLocation" label="安装位置" min-width="160" show-overflow-tooltip>
+            <template #default="scope">{{ scope.row.deviceLocation || '未填写' }}</template>
+          </el-table-column>
+          <el-table-column label="码流" min-width="170">
+            <template #default="scope">
+              <div>{{ profileLabel(scope.row) }}</div>
+              <small class="muted-text">{{ resolutionLabel(scope.row) }}</small>
+            </template>
+          </el-table-column>
+          <el-table-column label="状态" width="120">
+            <template #default="scope">
+              <el-tag :type="routeStatus(scope.row.actual).type" size="small">{{ routeStatus(scope.row.actual).label }}</el-tag>
+            </template>
+          </el-table-column>
+          <el-table-column prop="readers" label="当前观看" width="100" />
+          <el-table-column prop="detail" label="说明" min-width="220" show-overflow-tooltip />
+          <el-table-column label="操作" width="110" fixed="right">
+            <template #default="scope">
+              <el-button v-permisaction="['sense:liveview:view']" type="primary" link @click="handleWatch(scope.row)">实时查看</el-button>
+            </template>
+          </el-table-column>
+        </el-table>
+
+        <pagination
+          v-show="total > 0"
+          v-model:page="queryParams.pageIndex"
+          v-model:limit="queryParams.pageSize"
+          :total="total"
+          @pagination="getList"
+        />
+      </el-card>
+
+      <el-dialog v-model="playerOpen" width="min(1000px, 92vw)" :close-on-click-modal="false" destroy-on-close @closed="closePlayer">
+        <template #header>
+          <div class="dialog-header">
+            <div>
+              <strong>{{ currentRoute.deviceName || '实时视频' }}</strong>
+              <span>{{ profileLabel(currentRoute) }} · {{ currentRoute.deviceLocation || '未填写位置' }}</span>
+            </div>
+            <el-tag :type="playbackStatusType(playerState)">{{ playbackStatusLabel(playerState) }}</el-tag>
+          </div>
+        </template>
+
+        <SenseVideoPlayer
+          v-if="playerOpen"
+          :state="playerState"
+          :detail="playerDetail"
+          :player-url="session.playerUrl"
+          :retrying="retrying"
+          @retry="openSession"
+        />
+
+        <el-descriptions :column="3" border class="player-details">
+          <el-descriptions-item label="设备">{{ currentRoute.deviceName || '—' }}</el-descriptions-item>
+          <el-descriptions-item label="码流">{{ profileLabel(currentRoute) }}</el-descriptions-item>
+          <el-descriptions-item label="分辨率">{{ resolutionLabel(currentRoute) }}</el-descriptions-item>
+          <el-descriptions-item label="处理建议" :span="3">{{ playbackStatusDetail(playerState, playerDetail) }}</el-descriptions-item>
+        </el-descriptions>
+
+        <template #footer>
+          <el-button @click="playerOpen = false">关闭</el-button>
+          <el-button type="primary" :loading="retrying" @click="openSession">重新连接</el-button>
+        </template>
+      </el-dialog>
+    </template>
+  </BasicLayout>
+</template>
+
+<script>
+import { createLiveviewSession, getLiveviewSession, listLiveviewRoutes } from '@/api/sense/liveview'
+import SenseVideoPlayer from '@/components/sense/video-player'
+import { playbackStatusDetail, playbackStatusLabel, playbackStatusType, routeStatus } from './playbackStatus'
+
+export default {
+  name: 'SenseLiveview',
+  components: { SenseVideoPlayer },
+  data() {
+    return {
+      loading: false,
+      routes: [],
+      total: 0,
+      queryParams: { keyword: '', pageIndex: 1, pageSize: 10 },
+      playerOpen: false,
+      currentRoute: {},
+      session: {},
+      playerState: 'loading',
+      playerDetail: '',
+      retrying: false,
+      pollTimer: null,
+      timeoutTimer: null
+    }
+  },
+  created() {
+    this.getList()
+  },
+  beforeUnmount() {
+    this.stopTimers()
+  },
+  methods: {
+    playbackStatusDetail,
+    playbackStatusLabel,
+    playbackStatusType,
+    routeStatus,
+    profileLabel(route) {
+      if (!route || !route.id) return '—'
+      const kind = { main: '主码流', sub: '子码流', other: '其他码流' }[route.profileKind] || '码流'
+      return route.profileName ? `${kind}（${route.profileName}）` : kind
+    },
+    resolutionLabel(route) {
+      if (!route || !route.width || !route.height) return '未取得分辨率'
+      return `${route.width} × ${route.height}${route.encoding ? ` · ${route.encoding}` : ''}`
+    },
+    async getList() {
+      this.loading = true
+      try {
+        const response = await listLiveviewRoutes(this.queryParams)
+        this.routes = response.data.list || []
+        this.total = response.data.count || 0
+      } finally {
+        this.loading = false
+      }
+    },
+    handleQuery() {
+      this.queryParams.pageIndex = 1
+      this.getList()
+    },
+    resetQuery() {
+      this.$refs.queryForm.resetFields()
+      this.handleQuery()
+    },
+    handleWatch(route) {
+      this.currentRoute = { ...route }
+      this.playerOpen = true
+      this.openSession()
+    },
+    async openSession() {
+      if (!this.currentRoute.id || this.retrying) return
+      this.stopTimers()
+      this.retrying = true
+      this.playerState = 'loading'
+      this.playerDetail = ''
+      this.session = {}
+      try {
+        const response = await createLiveviewSession(this.currentRoute.id)
+        this.session = response.data
+        this.playerState = response.data.status
+        this.playerDetail = response.data.detail
+        this.startPolling()
+      } catch (error) {
+        this.playerState = 'offline'
+        this.playerDetail = error.message || ''
+      } finally {
+        this.retrying = false
+      }
+    },
+    startPolling() {
+      this.pollTimer = window.setInterval(this.refreshSession, 2000)
+      this.timeoutTimer = window.setTimeout(() => {
+        if (['loading', 'waiting'].includes(this.playerState)) {
+          this.playerState = 'timeout'
+          this.playerDetail = ''
+          this.stopTimers()
+        }
+      }, 20000)
+    },
+    async refreshSession() {
+      if (!this.session.id || !this.playerOpen) return
+      try {
+        const response = await getLiveviewSession(this.session.id)
+        this.session = response.data
+        this.playerState = response.data.status
+        this.playerDetail = response.data.detail
+        if (this.playerState === 'ready') {
+          window.clearTimeout(this.timeoutTimer)
+          this.timeoutTimer = null
+        } else if (!['loading', 'waiting'].includes(this.playerState)) {
+          this.stopTimers()
+        }
+      } catch (error) {
+        this.playerState = 'expired'
+        this.playerDetail = ''
+        this.stopTimers()
+      }
+    },
+    stopTimers() {
+      window.clearInterval(this.pollTimer)
+      window.clearTimeout(this.timeoutTimer)
+      this.pollTimer = null
+      this.timeoutTimer = null
+    },
+    closePlayer() {
+      this.stopTimers()
+      this.session = {}
+      this.currentRoute = {}
+      this.playerState = 'loading'
+      this.playerDetail = ''
+    }
+  }
+}
+</script>
+
+<style scoped>
+.page-header,
+.dialog-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 16px;
+}
+
+.page-header h3 {
+  margin: 0 0 8px;
+}
+
+.page-header p,
+.dialog-header span,
+.muted-text {
+  color: var(--el-text-color-secondary);
+}
+
+.dialog-header > div {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+
+.search-form,
+.empty-alert,
+.player-details {
+  margin-top: 16px;
+}
+
+.search-form :deep(.el-input) {
+  width: 320px;
+}
+
+.muted-text {
+  line-height: 1.5;
+}
+
+@media (max-width: 767px) {
+  .search-form :deep(.el-input) {
+    width: min(280px, 70vw);
+  }
+
+  .dialog-header {
+    align-items: flex-start;
+    flex-direction: column;
+  }
+}
+</style>
@@ -0,0 +1,46 @@
+const labels = {
+  loading: '正在连接',
+  waiting: '等待视频',
+  ready: '播放正常',
+  authentication_failed: '摄像头认证失败',
+  stream_not_found: '未找到视频流',
+  service_unavailable: '视频服务不可用',
+  timeout: '连接超时',
+  expired: '播放会话已过期',
+  offline: '视频已断开',
+  stopped: '视频已停止'
+}
+
+const details = {
+  loading: '正在建立短期播放会话，请稍候。',
+  waiting: '播放器已连接，正在等待摄像头开始传输画面。',
+  ready: '摄像头视频正在传输。',
+  authentication_failed: '请到“设备管理”更新摄像头账号或密码，再重新验证视频接入。',
+  stream_not_found: '请到“视频服务”执行对账，确认媒体路径已经恢复。',
+  service_unavailable: '请到“视频服务”检查 MediaMTX 进程和端口配置。',
+  timeout: '20 秒内未收到画面，请检查摄像头网络后重新连接。',
+  expired: '短期播放会话已失效，请重新连接。',
+  offline: '无法取得最新播放状态，请检查网络后重新连接。',
+  stopped: '该视频路径已停止，请先到“视频服务”恢复。'
+}
+
+export function playbackStatusLabel(value) {
+  return labels[value] || '暂时无法播放'
+}
+
+export function playbackStatusDetail(value, detail) {
+  return detail || details[value] || details.offline
+}
+
+export function playbackStatusType(value) {
+  if (value === 'ready') return 'success'
+  if (value === 'loading' || value === 'waiting') return 'warning'
+  if (value === 'stopped') return 'info'
+  return 'danger'
+}
+
+export function routeStatus(value) {
+  if (value === 'ready') return { label: '可观看', type: 'success' }
+  if (value === 'waiting') return { label: '等待观看', type: 'warning' }
+  return { label: '需要处理', type: 'danger' }
+}
@@ -0,0 +1,41 @@
+import SenseLiveview from '@/views/sense/liveview/index.vue'
+import { createLiveviewSession, getLiveviewSession, listLiveviewRoutes } from '@/api/sense/liveview'
+
+jest.mock('@/api/sense/liveview', () => ({
+  listLiveviewRoutes: jest.fn(),
+  createLiveviewSession: jest.fn(),
+  getLiveviewSession: jest.fn()
+}))
+
+describe('Sense live-view page lifecycle', () => {
+  beforeEach(() => {
+    jest.useFakeTimers()
+    listLiveviewRoutes.mockResolvedValue({ data: { list: [], count: 0 }})
+    createLiveviewSession.mockResolvedValue({ data: { id: 'view_test', playerUrl: '/api/v1/liveview/player/view_test', status: 'waiting', detail: '等待播放器连接' }})
+    getLiveviewSession.mockResolvedValue({ data: { id: 'view_test', playerUrl: '/api/v1/liveview/player/view_test', status: 'ready', detail: '上游拉流正常' }})
+  })
+
+  afterEach(() => {
+    jest.clearAllMocks()
+    jest.useRealTimers()
+  })
+
+  it('opens only the selected route and clears polling when unmounted', async() => {
+    const context = {
+      ...SenseLiveview.data(),
+      currentRoute: { id: 'device-1:main', deviceName: '东门摄像机' },
+      playerOpen: true
+    }
+    context.stopTimers = SenseLiveview.methods.stopTimers.bind(context)
+    context.refreshSession = SenseLiveview.methods.refreshSession.bind(context)
+    context.startPolling = SenseLiveview.methods.startPolling.bind(context)
+    await SenseLiveview.methods.openSession.call(context)
+
+    expect(createLiveviewSession).toHaveBeenCalledWith('device-1:main')
+    expect(context.session.playerUrl).toBe('/api/v1/liveview/player/view_test')
+    expect(jest.getTimerCount()).toBe(2)
+
+    SenseLiveview.beforeUnmount.call(context)
+    expect(jest.getTimerCount()).toBe(0)
+  })
+})
@@ -0,0 +1,32 @@
+import { mount } from '@vue/test-utils'
+import SenseVideoPlayer from '@/components/sense/video-player/index.vue'
+
+const ElButton = { emits: ['click'], template: '<button @click="$emit(\'click\')"><slot /></button>' }
+const ElIcon = { template: '<span><slot /></span>' }
+
+const mountPlayer = props => mount(SenseVideoPlayer, {
+  props,
+  global: { components: { ElButton, ElIcon }}
+})
+
+describe('Sense live-view player lifecycle', () => {
+  it('creates an iframe only for a selected playable session', () => {
+    const empty = mountPlayer({ state: 'loading', playerUrl: '' })
+    expect(empty.find('iframe').exists()).toBe(false)
+    empty.unmount()
+
+    const waiting = mountPlayer({ state: 'waiting', playerUrl: '/api/v1/liveview/player/view_test' })
+    expect(waiting.findAll('iframe')).toHaveLength(1)
+    expect(waiting.find('iframe').attributes('src')).toBe('/api/v1/liveview/player/view_test')
+    expect(waiting.attributes('aria-busy')).toBe('true')
+    waiting.unmount()
+  })
+
+  it('removes the iframe on timeout and offers an explicit retry', async() => {
+    const wrapper = mountPlayer({ state: 'timeout', playerUrl: '/api/v1/liveview/player/view_test' })
+    expect(wrapper.find('iframe').exists()).toBe(false)
+    expect(wrapper.text()).toContain('连接超时')
+    await wrapper.find('button').trigger('click')
+    expect(wrapper.emitted('retry')).toHaveLength(1)
+  })
+})
@@ -0,0 +1,16 @@
+import { playbackStatusDetail, playbackStatusLabel, playbackStatusType, routeStatus } from '@/views/sense/liveview/playbackStatus'
+
+describe('Sense live-view playback states', () => {
+  it('keeps authentication, missing stream and timeout actionable', () => {
+    expect(playbackStatusLabel('authentication_failed')).toBe('摄像头认证失败')
+    expect(playbackStatusDetail('stream_not_found')).toContain('视频服务')
+    expect(playbackStatusDetail('timeout')).toContain('20 秒')
+    expect(playbackStatusType('offline')).toBe('danger')
+  })
+
+  it('maps route readiness without relying on color alone', () => {
+    expect(routeStatus('ready')).toEqual({ label: '可观看', type: 'success' })
+    expect(routeStatus('waiting')).toEqual({ label: '等待观看', type: 'warning' })
+    expect(routeStatus('apply_failed').label).toBe('需要处理')
+  })
+})
@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Architecture-and-Code-Map
 wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Architecture-and-Code-Map.-
-wiki_revision: c5482806a40428a436c202760eefdb6403406584
-synchronized_at: 2026-08-14T09:46:37Z
+wiki_revision: 0a15795aa69c5a0279a42ff1b48b44ddf68a9fad
+synchronized_at: 2026-08-14T10:45:46Z
 <!-- gitea-wiki-mirror:end -->

 # 架构与代码地图
@@ -100,6 +100,10 @@ ONVIF 支持 Basic 与 MD5/SHA-256 Digest challenge，Profile 与无凭据 Strea

 媒体路由只保存设备/Profile 引用、无秘密路径名、期望态、实际态、reader、退避和下次重试；摄像头凭据从内部端口按需解密，仅在 loopback Control API 请求内临时组装，不写入路由表、基础配置、日志或 Sense 响应。MediaMTX 故障和退避不改变 #66 的设备/Profile 验证状态。

+工单 #68 在 `Sense/server/app/sense/liveview/` 建立单路监看投影和短期播放会话：认证 API 只返回设备/Profile 展示字段、播放状态和同源短期播放器地址，不返回 RTSP URI、摄像头凭据或 MediaMTX 内部路径。播放能力令牌使用 192 位随机值、绑定登录用户、同一用户只保留一个活动会话，登录页面持续轮询时按 2 分钟无活动窗口续期；关闭页面后停止续期。
+
+`Sense/server/app/admin/router/sense_liveview.go` 将列表、创建会话和状态查询接入 GoAdmin JWT/Casbin，短期播放器包装页只凭不可猜测能力令牌访问，并设置 no-store、no-referrer、SAMEORIGIN 与 CSP。前端入口为 `Sense/ui/src/views/sense/liveview/index.vue`，复用 BasicLayout、Element Plus 表格/分页/Dialog/Tag 和权限指令；仅 `Sense/ui/src/components/sense/video-player/` 是业务专用播放器组件，任一时刻只建立一路 reader。
+
 <!-- sense-runtime:end -->

 <!-- sense-mvp:start -->
@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Business-Rules-and-Glossary
 wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Business-Rules-and-Glossary.-
-wiki_revision: ea2c540a9ac3f8ccf40123f8389eb392fb5e172b
-synchronized_at: 2026-08-14T09:46:41Z
+wiki_revision: e80685e19115e26384d58ddee8a15e5d80b03bb4
+synchronized_at: 2026-08-14T10:45:50Z
 <!-- gitea-wiki-mirror:end -->

 # 业务规则与术语
@@ -85,6 +85,14 @@ synchronized_at: 2026-08-14T09:46:41Z
 - 路径状态区分 pending、waiting、ready、process_unavailable、apply_failed、status_unavailable、path_missing、stopped，并保存失败次数和有上限的下次重试时间。
 - 冷启动恢复 desired=running 路径；用户明确停止的路径保持 stopped，不因启动扫描自动重新启用。稳定路径只刷新状态，不重复下发配置或无意义增加版本。
 - MediaMTX 失败不得删除或降级设备台账与最后一次已验证 Profile。
+### Sense 实时监看规则
+
+- 设备/Profile 列表必须分页和搜索；16/128 路不能导致页面同时创建全部播放器。用户选择一路并打开 Dialog 后才建立 reader，关闭或切换时销毁当前播放器。
+- 页面和 JSON API 不返回 RTSP URI、摄像头凭据或 MediaMTX 内部路径。播放器只使用同源短期能力地址；能力令牌必须高熵、绑定用户、每用户单会话，并在停止认证轮询后最多 2 分钟失效。
+- 播放状态必须区分 loading、waiting、ready、authentication_failed、stream_not_found、service_unavailable、timeout、expired、offline 和 stopped，并同时显示文字与可行动处理建议，不能只用颜色表达。
+- waiting 表示媒体路径存在且播放器正在建立 reader，不等于摄像头接入失败；20 秒仍未就绪才显示连接超时并允许显式重连。
+- 默认从浏览器访问 Sense 的主机名推导 MediaMTX WebRTC 端口 8889；经过反向代理、HTTPS 或端口映射时，部署方必须显式配置安全的 `SENSE_MEDIAMTX_WEBRTC_PUBLIC_BASE`，不得回退到只对服务器自身有效的地址。
+
 <!-- sense-media:end -->

 <!-- sense-mvp:start -->
@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Local-Development-and-Verification
 wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Local-Development-and-Verification.-
-wiki_revision: e084a4ae3f5038c4ec7dae6028a2e3d7527680a8
-synchronized_at: 2026-08-14T09:46:47Z
+wiki_revision: 95be7e2aa152205f524a185897dff5eb2c7e7e04
+synchronized_at: 2026-08-14T10:45:55Z
 <!-- gitea-wiki-mirror:end -->

 # 本地开发与验证
@@ -190,6 +190,36 @@ go test ./cmd/migrate/migration/version -run TestMediaMigrationOnPostgres -v

 测试必须使用隔离端口和数据库；结束后停止测试进程。不得输出连接串或摄像头凭据。

+### Sense 实时监看
+
+浏览器直接访问 Sense 所在主机且 MediaMTX 使用默认 WebRTC 端口 8889 时无需额外变量。反向代理、HTTPS 或端口映射部署必须在 Sense 进程环境提供浏览器可达的基础地址；值只能是无用户信息、查询和片段的 HTTP(S) origin：
+
+```powershell
+$env:SENSE_MEDIAMTX_WEBRTC_PUBLIC_BASE = 'http://<浏览器可达主机>:8889'
+```
+
+不要填写 RTSP 地址、Control API 地址、摄像头凭据或服务器内部文件路径。HTTPS 页面不得嵌入 HTTP 视频地址；应为 MediaMTX WebRTC 配置 HTTPS 或受控同源代理后填写对应 HTTPS origin。
+
+定向与回归验证：
+
+```powershell
+cd Sense/server
+go test -race ./app/sense/liveview
+go test ./...
+go vet ./...
+go build ./...
+
+$env:SENSE_LIVEVIEW_MIGRATION_TEST_DATABASE_URL = '<隔离 PostgreSQL 连接>'
+go test ./cmd/migrate/migration/version -run TestLiveviewMigrationOnPostgres -count=1 -v
+
+cd ../ui
+corepack pnpm@9.15.1 lint
+corepack pnpm@9.15.1 test:unit
+corepack pnpm@9.15.1 build:prod
+```
+
+真实 smoke 使用隔离端口、MediaMTX 和合成 RTSP：浏览器打开 WebRTC 播放地址后必须取得非零视频尺寸和可播放 readyState，并确认任一时刻只存在一个播放器。结束后停止测试 MediaMTX/FFmpeg/浏览器并删除临时目录。客户真实摄像机与现场网络仍需获得授权后验证，记录状态而不记录地址、URI 或凭据。
+
 <!-- sense-runtime:end -->


@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Troubleshooting
 wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Troubleshooting
-wiki_revision: c615cd5235557a3888260beb5a682c6ed4e5b5dc
-synchronized_at: 2026-08-14T09:46:56Z
+wiki_revision: 331755cb39ac9d63c188395c5caafe0815d64975
+synchronized_at: 2026-08-14T10:46:04Z
 <!-- gitea-wiki-mirror:end -->

 # 故障排查
@@ -85,6 +85,19 @@ synchronized_at: 2026-08-14T09:46:56Z
 | 显示外部启动（受保护） | Sense 检测到不是本实例启动的 MediaMTX；孤儿安全闸生效，Sense 关闭时不会停止它。 |
 | 持续自动重试 | 查看失败码、失败次数和下次重试时间；修正二进制、端口、凭据或上游后等待退避到期，或由有权限用户立即对账。 |
 | Sense 重启后路径未恢复 | 确认数据库 route 的 desired 为 running、迁移已执行、Control API 可达；明确停止的路径不会自动恢复。 |
+### Sense 实时监看排错
+
+| 现象 | 原因与处理 |
+|---|---|
+| 浏览器提示 127.0.0.1 拒绝连接 | 127.0.0.1 指向使用者电脑，不一定是 Sense 服务器；将 `SENSE_MEDIAMTX_WEBRTC_PUBLIC_BASE` 配成浏览器实际可达的 MediaMTX HTTP(S) origin，并检查 8889 或映射端口。 |
+| `stream not found` / 未找到视频流 | 路径未恢复或 Profile 已失效；先到“视频服务”对账，确认路径存在，再重新打开实时监看建立 reader。不要把内部路径手工拼进页面。 |
+| 一直显示“等待视频” | 播放器已创建但 sourceOnDemand 尚未 ready；保持 Dialog 打开并检查摄像头 RTSP、WebRTC 端口和 MediaMTX reader。20 秒后页面会转为超时并提供重连。 |
+| 摄像头认证失败 | 到“设备管理”更新凭据，再到“视频接入”重新验证；页面不会显示或回填旧凭据。 |
+| 视频服务不可用 | 到“视频服务”检查 MediaMTX 进程、Control API、WebRTC 端口和路径对账，不要只刷新浏览器。 |
+| 播放会话已过期 | 页面关闭、网络中断或认证轮询停止超过 2 分钟；重新连接会生成新能力令牌，旧地址不应继续可用。 |
+| HTTPS 页面无法播放 HTTP 视频 | 浏览器阻止混合内容；为 MediaMTX WebRTC 配置 HTTPS 或受控同源代理，并把公开基础地址改成 HTTPS。 |
+| 服务端 curl 正常、浏览器仍失败 | 服务端可达不代表客户端可达；从实际用户浏览器检查公开主机、端口、防火墙、证书和 WebRTC UDP/TCP 路径。 |
+
 <!-- sense-media:end -->

 <!-- sense-admission:end -->
@@ -0,0 +1,81 @@
+<!-- gitea-wiki-mirror:start -->
+generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
+wiki_page: Task-68-Sense单路实时监看与播放状态反馈
+wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Task-68-Sense%E5%8D%95%E8%B7%AF%E5%AE%9E%E6%97%B6%E7%9B%91%E7%9C%8B%E4%B8%8E%E6%92%AD%E6%94%BE%E7%8A%B6%E6%80%81%E5%8F%8D%E9%A6%88.-
+wiki_revision: 88e542d512e472274a74e443a761217e24618941
+synchronized_at: 2026-08-15T00:40:11Z
+<!-- gitea-wiki-mirror:end -->
+
+# 68 Sense单路实时监看与播放状态反馈
+
+- 类型：需求
+- 所属 Epic：#7
+- 所属 MVP / 版本：#8
+- 状态：已完成
+- 日期：2026-08-14
+- Gitea 工单：https://git.ilapage.cn/ila/yovision/issues/68
+- Pull Request：https://git.ilapage.cn/ila/yovision/pulls/86
+- 主项目：Sense
+
+## 背景与目标
+
+在 #67 已对账的 MediaMTX 路径上，为网管和非技术人员提供设备/Profile 搜索、分页和单路实时查看。Brain、Bell 不启动时可独立运行；页面不得暴露摄像头凭据、RTSP URI或内部媒体路径。
+
+## 最终方案
+
+- 后端在 `app/sense/liveview` 建立只含展示字段的分页投影，最多返回 50 条，不把 16/128 路变成硬上限。
+- 登录用户选择一路后创建 192 位随机播放能力；令牌绑定用户、同用户只保留一个会话，认证轮询时按 2 分钟无活动窗口续期，关闭页面后失效。
+- JSON 只返回同源 `/api/v1/liveview/player/<能力>`；包装页使用 no-store、no-referrer、SAMEORIGIN 与 CSP，再嵌入浏览器可达的 MediaMTX WebRTC 页面。
+- 默认由 Sense 请求主机推导 WebRTC 8889；反向代理、HTTPS 或端口映射通过安全的 `SENSE_MEDIAMTX_WEBRTC_PUBLIC_BASE` 显式配置。
+- 复用 GoAdmin Router/JWT/Casbin/迁移/动态菜单及 go-admin-ui BasicLayout、Axios、Element Plus 搜索/表格/分页/Dialog/Tag/权限按钮；只新增播放器业务组件。
+- waiting 时先保留 iframe 建立 reader；ready 后持续轮询，20 秒未就绪显示超时。关闭 Dialog 或组件卸载会清理 iframe、轮询和超时计时器。
+- 状态区分 loading、waiting、ready、authentication_failed、stream_not_found、service_unavailable、timeout、expired、offline 和 stopped，并给出可行动中文处理建议。
+
+## 修改文件
+
+- `Sense/server/app/sense/liveview/**`：分页投影、短期会话、播放器包装页及测试。
+- `Sense/server/app/admin/router/sense_liveview.go`：认证 API 与短期播放器路由。
+- `Sense/server/cmd/migrate/migration/version/*liveview*`：菜单、角色和 Casbin 权限。
+- `Sense/ui/src/views/sense/liveview/**`、`api/sense/liveview.js`：实时监看页面、状态映射和请求。
+- `Sense/ui/src/components/sense/video-player/**`：唯一业务专用播放器组件。
+- `Sense/ui/tests/unit/sense/liveview*.spec.js`：状态、iframe 和页面计时器生命周期测试。
+- Wiki Architecture、Business Rules、Local Development、Troubleshooting：架构、安全、配置、验证和排错。
+
+## 验收结果
+
+| 验收标准 | 结果 |
+|---|---|
+| 设备与 Profile 可搜索、分页并进入单路实时监看 | 通过 |
+| waiting 且播放 URL 有效时建立 reader，不循环等待 | 通过；真实合成 WebRTC smoke |
+| 加载、空、认证失败、stream not found、重连和超时可区分 | 通过 |
+| 页面不暴露凭据与内部文件路径 | 通过；DTO/JSON 测试与扫描 |
+| 128 路使用分页且不同时创建全部播放器 | 通过；服务端最大页 50，前端单 Dialog |
+| 通用组件无重复实现且播放器风格一致 | 通过 |
+
+## 测试
+
+- `go test ./...`、`go vet ./...`、`go build ./...`：通过。
+- `go test -race ./app/sense/liveview`：通过。
+- PostgreSQL 17 隔离迁移：1 个菜单、9 条 Casbin 策略、1 条迁移记录通过；临时实例/schema/目录已清理。
+- 前端 lint：0 error，32 条冻结上游 warning。
+- 前端单测：13 suites、40 tests 通过。
+- 前端生产构建：通过，6 条冻结上游 warning。
+- MediaMTX v1.19.3 + FFmpeg 合成 RTSP + Edge WebRTC：640×360、readyState=4、自动播放中；临时进程、配置和自动证书已清理。
+- Wiki 页面读取确认并成功导出镜像。
+- **未验证部分**：客户真实摄像机、现场防火墙/证书、实际部署反向代理和客户目标浏览器，需授权现场验收。
+
+## 风险与回退
+
+回退 PR #86 可移除实时监看入口、会话 API、菜单和播放器组件；#67 的设备/Profile、媒体路由与 MediaMTX 生命周期不受影响。内存会话随进程退出自然失效，无数据库业务数据需要回滚。
+
+## 相关提交
+
+- `c63c623` feat: 重建 Sense 单路实时监看 (#68)
+- `a279a1e` docs: 记录 Sense 实时监看架构 (#68)
+
+
+## 人工验收
+
+- 验收日期：2026-08-15
+- 验收结论：用户明确回复“#68 验收通过”。
+- 后续处理：按分支治理将 PR #86 合入 `dev`，关闭单元工单，并在 MVP #8 与 Epic #7 更新索引；不修改 `main`。
@@ -119,6 +119,10 @@
    {
      "page": "Task-67-Sense视频服务生命周期与状态对账",
      "path": "docs/task/67-Sense视频服务生命周期与状态对账.md"
+    },
+    {
+      "page": "Task-68-Sense单路实时监看与播放状态反馈",
+      "path": "docs/task/68-Sense单路实时监看与播放状态反馈.md"
    }
  ]
 }