优化，预拉取docker镜像

VERSION

@@ -1 +1 @@
-v1.0.3
+v1.0.4

backend/apps/common/services/__init__.py

@@ -0,0 +1,10 @@
+"""
+通用服务模块
+
+提供系统级别的公共服务，包括：
+- SystemLogService: 系统日志读取服务
+"""
+
+from .system_log_service import SystemLogService
+
+__all__ = ['SystemLogService']

backend/apps/common/services/system_log_service.py

@@ -1,3 +1,12 @@
+"""
+系统日志服务模块
+
+提供系统日志的读取和处理功能，支持：
+- 从多个日志目录读取日志文件
+- 按时间戳排序日志条目
+- 限制返回行数，防止内存溢出
+"""
+
 import glob
 import json
 import logging
@@ -9,16 +18,34 @@ logger = logging.getLogger(__name__)
 
 
 class SystemLogService:
+    """
+    系统日志服务类
+    
+    负责读取和处理系统日志文件，支持从容器内路径或宿主机挂载路径读取日志。
+    日志会按时间戳排序后返回，支持 JSON 格式的结构化日志解析。
+    """
+    
     def __init__(self):
+        # 日志文件搜索路径（按优先级排序，找到第一个有效路径后停止）
         self.log_globs = [
-            "/app/backend/logs/*",
-            "/opt/xingrin/logs/*",
+            "/app/backend/logs/*",      # Docker 容器内路径
+            "/opt/xingrin/logs/*",      # 宿主机挂载路径
         ]
-        self.default_lines = 200
-        self.max_lines = 10000
-        self.timeout_seconds = 3
+        self.default_lines = 200        # 默认返回行数
+        self.max_lines = 10000          # 最大返回行数限制
+        self.timeout_seconds = 3        # tail 命令超时时间
 
     def get_logs_content(self, lines: int | None = None) -> str:
+        """
+        获取系统日志内容
+        
+        Args:
+            lines: 返回的日志行数，默认 200 行，最大 10000 行
+            
+        Returns:
+            str: 按时间排序的日志内容，每行以换行符分隔
+        """
+        # 参数校验和默认值处理
         if lines is None:
             lines = self.default_lines
 
@@ -28,15 +55,20 @@ class SystemLogService:
         if lines > self.max_lines:
             lines = self.max_lines
 
+        # 查找日志文件（按优先级匹配第一个有效的日志目录）
         files: list[str] = []
         for pattern in self.log_globs:
             matched = sorted(glob.glob(pattern))
             if matched:
                 files = matched
                 break
+        
         if not files:
             return ""
 
+        # 使用 tail 命令读取日志文件末尾内容
+        # -q: 静默模式，不输出文件名头
+        # -n: 指定读取行数
         cmd = ["tail", "-q", "-n", str(lines), *files]
 
         result = subprocess.run(
@@ -54,12 +86,16 @@ class SystemLogService:
                 (result.stderr or "").strip(),
             )
 
+        # 过滤空行
         raw = result.stdout or ""
         raw_lines = [ln for ln in raw.splitlines() if ln.strip()]
 
+        # 解析日志行，提取时间戳用于排序
+        # 支持 JSON 格式日志（包含 asctime 字段）和方括号格式 [2025-12-17 17:09:06]
         parsed: list[tuple[datetime | None, int, str]] = []
         for idx, line in enumerate(raw_lines):
             ts: datetime | None = None
+            # 尝试解析 JSON 格式日志
             if line.startswith("{") and line.endswith("}"):
                 try:
                     obj = json.loads(line)
@@ -68,10 +104,23 @@ class SystemLogService:
                         ts = datetime.strptime(asctime, "%Y-%m-%d %H:%M:%S")
                 except Exception:
                     ts = None
+            # 尝试解析方括号格式日志: [2025-12-17 17:09:06]
+            elif line.startswith("["):
+                try:
+                    # 提取第一个方括号内的时间戳
+                    end_bracket = line.find("]")
+                    if end_bracket > 1:
+                        time_str = line[1:end_bracket]
+                        ts = datetime.strptime(time_str, "%Y-%m-%d %H:%M:%S")
+                except Exception:
+                    ts = None
             parsed.append((ts, idx, line))
 
+        # 按时间戳排序（无时间戳的行排在最后，保持原始顺序）
         parsed.sort(key=lambda x: (x[0] is None, x[0] or datetime.min, x[1]))
         sorted_lines = [x[2] for x in parsed]
+        
+        # 截取最后 N 行
         if len(sorted_lines) > lines:
             sorted_lines = sorted_lines[-lines:]
 

backend/apps/common/urls.py

@@ -1,13 +1,21 @@
 """
 通用模块 URL 配置
+
+路由说明：
+- /api/auth/*     认证相关接口（登录、登出、用户信息）
+- /api/system/*   系统管理接口（日志查看等）
 """
+
 from django.urls import path
 from .views import LoginView, LogoutView, MeView, ChangePasswordView, SystemLogsView
 
 urlpatterns = [
+    # 认证相关
     path('auth/login/', LoginView.as_view(), name='auth-login'),
     path('auth/logout/', LogoutView.as_view(), name='auth-logout'),
     path('auth/me/', MeView.as_view(), name='auth-me'),
     path('auth/change-password/', ChangePasswordView.as_view(), name='auth-change-password'),
+    
+    # 系统管理
     path('system/logs/', SystemLogsView.as_view(), name='system-logs'),
 ]

backend/apps/common/views/__init__.py

@@ -1,3 +1,11 @@
+"""
+通用模块视图导出
+
+包含：
+- 认证相关视图：登录、登出、用户信息、修改密码
+- 系统日志视图：实时日志查看
+"""
+
 from .auth_views import LoginView, LogoutView, MeView, ChangePasswordView
 from .system_log_views import SystemLogsView
 

backend/apps/common/views/system_log_views.py

@@ -1,3 +1,9 @@
+"""
+系统日志视图模块
+
+提供系统日志的 REST API 接口，供前端实时查看系统运行日志。
+"""
+
 import logging
 
 from django.utils.decorators import method_decorator
@@ -15,6 +21,26 @@ logger = logging.getLogger(__name__)
 
 @method_decorator(csrf_exempt, name="dispatch")
 class SystemLogsView(APIView):
+    """
+    系统日志 API 视图
+    
+    GET /api/system/logs/
+        获取系统日志内容
+        
+    Query Parameters:
+        lines (int, optional): 返回的日志行数，默认 200，最大 10000
+        
+    Response:
+        {
+            "content": "日志内容字符串..."
+        }
+        
+    Note:
+        - 当前为开发阶段，暂时允许匿名访问
+        - 生产环境应添加管理员权限验证
+    """
+    
+    # TODO: 生产环境应改为 IsAdminUser 权限
     authentication_classes = []
     permission_classes = [AllowAny]
 
@@ -23,10 +49,17 @@ class SystemLogsView(APIView):
         self.service = SystemLogService()
 
     def get(self, request):
+        """
+        获取系统日志
+        
+        支持通过 lines 参数控制返回行数，用于前端分页或实时刷新场景。
+        """
         try:
+            # 解析 lines 参数
             lines_raw = request.query_params.get("lines")
             lines = int(lines_raw) if lines_raw is not None else None
 
+            # 调用服务获取日志内容
             content = self.service.get_logs_content(lines=lines)
             return Response({"content": content})
         except ValueError:

install.sh

@@ -388,6 +388,21 @@ fi
 # 准备 HTTPS 证书（无域名也可使用自签）
 generate_self_signed_cert
 
+# ==============================================================================
+# 预拉取 Worker 镜像（避免扫描时等待）
+# ==============================================================================
+step "预拉取 Worker 镜像..."
+DOCKER_USER=$(grep "^DOCKER_USER=" "$DOCKER_DIR/.env" 2>/dev/null | cut -d= -f2)
+DOCKER_USER=${DOCKER_USER:-yyhuni}
+WORKER_IMAGE="${DOCKER_USER}/xingrin-worker:${APP_VERSION}"
+
+info "正在拉取: $WORKER_IMAGE"
+if docker pull "$WORKER_IMAGE"; then
+    success "Worker 镜像拉取完成"
+else
+    warn "Worker 镜像拉取失败，扫描时会自动重试拉取"
+fi
+
 # ==============================================================================
 # 启动服务
 # ==============================================================================