@xcanwin/manyoyo 7.1.6 → 8.0.1

package/lib/web/server.js

@@ -5,14 +5,25 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 const crypto = require('crypto');
+const { consumeLoginToken, isLoopbackHost } = require('../login-token');
 const http = require('http');
 const WebSocket = require('ws');
 const JSON5 = require('json5');
 const { buildContainerRunArgs } = require('../container-run');
+const { applyAptMirror } = require('../mirrors');
+const { normalizeMirrors } = require('../runtime-normalizers');
 const { estimateContainerCapacity } = require('../capacity');
 const { extractAgentMessageFromCodexJsonl } = require('../codex-output');
 const { findValueRangeByPath, applyTextReplacements, upsertValueByPath } = require('../json5-text-edit');
 const { resolveRuntimeConfig } = require('../runtime-resolver');
+const { AGENT_ENV_SCHEMA } = require('../init-config');
+const { ensureImagePresent, pullImageProcess } = require('../image-pull');
+const { waitForImport } = require('../offline-import');
+const { baseRawOf, buildAgentConfigRaw, buildPasswordConfigRaw, shouldWriteMirrors, buildMirrorsConfigRaw } = require('../setup-config');
+const { listSetupAgents, getConfiguredAgents, buildAgentRunProfile, classifyConnectionResult, redactSecrets, validateSetupPassword, listMirrorPresets } = require('../setup');
+const { applyDoctorFixes } = require('../doctor');
+const { writeConfigFileSecure } = require('../secure-file');
+const { sanitizeSensitiveData, sanitizeServeLogText } = require('../serve-log');
 const {
     parseEnvEntry,
     expandHomeAliasPath,
@@ -87,7 +98,7 @@ const DEFAULT_WEB_CONFIG_TEMPLATE = `{
     "containerName": "my-dev",
     "hostPath": "/path/to/your/project",
     "containerPath": "/path/to/your/project",
-    "imageName": "localhost/xcanwin/manyoyo",
+    "imageName": "ghcr.io/xcanwin/manyoyo",
     "imageVersion": "1.7.4-common",
     "containerMode": "common",
     "shellPrefix": "",
@@ -1188,7 +1199,7 @@ function runAgentProtocolProcess(ctx, containerName, command, options = {}) {
         let stdoutAll = '';
         let child;
         try {
-            child = spawn(ctx.dockerCmd, ['exec', '-i', containerName, '/bin/bash', '-lc', command], { stdio: ['pipe', 'pipe', 'pipe'] });
+            child = spawn(ctx.dockerCmd, ['exec', '-i', containerName, '/bin/bash', '-lc', command], { stdio: ['pipe', 'pipe', 'pipe'], env: ctx.dockerEnv });
         } catch (e) {
             resolve({ result: null, stdout: '' });
             return;
@@ -2587,6 +2598,9 @@ function validateWebConfigShape(configObject) {
     if (hasOwn(config, 'ports')) {
         normalizeStringArray(config.ports, 'ports');
     }
+    if (hasOwn(config, 'mirrors')) {
+        normalizeMirrors(config.mirrors);
+    }
     if (hasOwn(config, 'agentPromptCommand')) {
         normalizeAgentPromptCommandTemplate(config.agentPromptCommand, 'agentPromptCommand');
     }
@@ -3179,6 +3193,138 @@ function listWebManyoyoContainers(ctx) {
     return map;
 }
 
+function webImageRef(ctx, runtime) {
+    return `${runtime ? runtime.imageName : ctx.imageName}:${runtime ? runtime.imageVersion : ctx.imageVersion}`;
+}
+
+const IMAGE_INSPECT_TIMEOUT_MS = 10000;
+
+// 异步 + 超时：daemon 卡住时不能占住事件循环（向导每隔几秒轮询 /api/setup/status）
+async function isWebImagePresent(ctx, imageRef) {
+    try {
+        if (ctx.dockerExecAsync) {
+            await ctx.dockerExecAsync(['image', 'inspect', imageRef], { timeout: IMAGE_INSPECT_TIMEOUT_MS });
+        } else {
+            ctx.dockerExecArgs(['image', 'inspect', imageRef], { stdio: 'pipe' });
+        }
+        return true;
+    } catch (e) {
+        return false;
+    }
+}
+
+function createImagePreparingError(message) {
+    const error = new Error(message);
+    error.statusCode = 409;
+    error.imagePreparing = true;
+    return error;
+}
+
+// 本地没有镜像就在后台拉取（异步进程，不阻塞事件循环）；同一镜像并发请求共用一次拉取。
+// 进度写在 state.imagePulls，/api/setup/status 会读它。
+async function ensureWebImage(ctx, state, imageRef, options = {}) {
+    // 离线安装器正在后台导入镜像：不要同时去仓库拉同一个镜像。
+    // 面向请求的调用（options.failFast）直接返回“镜像准备中”，不把 HTTP 请求挂起几分钟；后台预拉取才等待。
+    if (ctx.importState().active) {
+        if (options.failFast) {
+            throw createImagePreparingError('镜像正在导入，请稍后再试（向导顶部进度条显示进度）');
+        }
+        await waitForImport({ readState: ctx.importState });
+    }
+    const current = state.imagePulls.get(imageRef);
+    if (current && current.status === 'pulling') {
+        if (options.failFast) {
+            throw createImagePreparingError('镜像正在拉取，请稍后再试（向导顶部进度条显示进度）');
+        }
+        await current.promise;
+        return;
+    }
+    if (await isWebImagePresent(ctx, imageRef)) {
+        state.imagePulls.delete(imageRef);
+        return;
+    }
+    const entry = { status: 'pulling', message: '正在拉取镜像', promise: null };
+    entry.promise = ensureImagePresent({
+        imageRef,
+        command: ctx.dockerCmd,
+        isPresent: () => false,
+        pull: () => pullImageProcess({
+            command: ctx.dockerCmd,
+            env: ctx.dockerEnv,
+            imageRef,
+            onOutput: text => {
+                const lastLine = String(text).split(/[\r\n]+/).map(line => line.trim()).filter(Boolean).pop();
+                if (lastLine) entry.message = lastLine.slice(0, 200);
+            }
+        })
+    }).then(() => {
+        state.imagePulls.delete(imageRef);
+    }, error => {
+        entry.status = 'failed';
+        entry.message = error.message;
+        throw error;
+    });
+    state.imagePulls.set(imageRef, entry);
+    await entry.promise;
+}
+
+// serve 启动后等容器环境就绪，再在后台把默认镜像拉好，首次向导的进度条才会走完
+function startWebImagePrepare(ctx, state) {
+    const imageRef = webImageRef(ctx);
+    const deadline = Date.now() + 10 * 60 * 1000;
+    const tick = () => {
+        const status = ctx.runtimeState.status;
+        if (status === 'ready') {
+            ensureWebImage(ctx, state, imageRef).catch(e => ctx.logger.warn('image prepare failed', { message: e.message }));
+            return;
+        }
+        if (status === 'failed' || Date.now() > deadline) return;
+        setTimeout(tick, 1000).unref();
+    };
+    tick();
+}
+
+const SETUP_TEST_CONTAINER_PREFIX = 'manyoyo-setup-test-';
+
+// 连接测试的一次性容器带着用户的 API Key：serve 被强杀时 finally 不会执行，下次启动（运行时就绪后）清掉残留
+async function cleanupStaleSetupTestContainers(ctx) {
+    if (!ctx.dockerExecAsync) return;
+    try {
+        const listed = await ctx.dockerExecAsync(['ps', '-a', '--filter', `name=${SETUP_TEST_CONTAINER_PREFIX}`, '--format', '{{.Names}}'], { timeout: 10000 });
+        const names = String(listed || '').split('\n').map(line => line.trim())
+            .filter(name => name.startsWith(SETUP_TEST_CONTAINER_PREFIX) && /^[A-Za-z0-9_.-]+$/.test(name));
+        for (const name of names) {
+            await ctx.dockerExecAsync(['rm', '-f', name], { timeout: 20000 }).catch(() => {});
+        }
+    } catch (e) {
+        ctx.logger.warn('cleanup stale setup test containers failed', { message: e && e.message });
+    }
+}
+
+function startStaleSetupCleanup(ctx) {
+    const deadline = Date.now() + 10 * 60 * 1000;
+    const tick = () => {
+        const status = ctx.runtimeState.status;
+        if (status === 'ready') {
+            cleanupStaleSetupTestContainers(ctx);
+            return;
+        }
+        if (status === 'failed' || Date.now() > deadline) return;
+        setTimeout(tick, 1000).unref();
+    };
+    tick();
+}
+
+// 软件源每次创建容器时现读配置：向导/系统设置里改了马上对新容器生效；配置写坏时退回官方默认
+function readWebMirrors(state) {
+    try {
+        const snapshot = readWebConfigSnapshot(state.webConfigPath);
+        return normalizeMirrors(snapshot.parseError ? undefined : (snapshot.parsed || {}).mirrors);
+    } catch (e) {
+        return normalizeMirrors(undefined);
+    }
+}
+
 async function ensureWebContainer(ctx, state, containerInput, messageSessionRef = null) {
     const runtime = typeof containerInput === 'string'
         ? buildStaticContainerRuntime(ctx, containerInput)
@@ -3189,7 +3335,9 @@ async function ensureWebContainer(ctx, state, containerInput, messageSessionRef
     }
 
     if (!ctx.containerExists(runtime.containerName)) {
+        const mirrors = readWebMirrors(state);
         const args = buildContainerRunArgs({
+            mirrors,
             containerName: runtime.containerName,
             hostPath: runtime.hostPath,
             containerPath: runtime.containerPath,
@@ -3203,6 +3351,8 @@ async function ensureWebContainer(ctx, state, containerInput, messageSessionRef
             defaultCommand: runtime.defaultCommand
         });
 
+        await ensureWebImage(ctx, state, webImageRef(ctx, runtime), { failFast: true });
+
         try {
             ctx.dockerExecArgs(args, { stdio: 'pipe' });
         } catch (e) {
@@ -3210,7 +3360,13 @@ async function ensureWebContainer(ctx, state, containerInput, messageSessionRef
             throw e;
         }
 
-        await ctx.waitForContainerReady(runtime.containerName);
+        await ctx.waitForContainerReady(runtime.containerName, { throwOnFailure: true });
+        applyAptMirror({
+            dockerExecArgs: ctx.dockerExecArgs,
+            containerName: runtime.containerName,
+            mirrors,
+            warn: message => console.warn(message)
+        });
         appendWebSessionMessage(
             state.webHistoryDir,
             messageSessionRef || runtime.containerName,
@@ -3239,7 +3395,7 @@ async function execCommandInWebContainer(ctx, containerName, command, options =
         const process = spawn(
             ctx.dockerCmd,
             ['exec', containerName, '/bin/bash', '-lc', command],
-            { stdio: ['ignore', 'pipe', 'pipe'] }
+            { stdio: ['ignore', 'pipe', 'pipe'], env: ctx.dockerEnv }
         );
 
         const MAX_RAW_OUTPUT_CHARS = 32 * 1024 * 1024;
@@ -3307,7 +3463,7 @@ function spawnContainerRawFileStream(ctx, containerName, filePath) {
     return spawn(
         ctx.dockerCmd,
         ['exec', containerName, 'cat', '--', filePath],
-        { stdio: ['ignore', 'pipe', 'pipe'] }
+        { stdio: ['ignore', 'pipe', 'pipe'], env: ctx.dockerEnv }
     );
 }
 
@@ -3645,7 +3801,7 @@ async function execAgentInWebContainerStream(ctx, state, sessionRefOrContainerNa
         process = spawn(
             ctx.dockerCmd,
             ['exec', sessionRef.containerName, '/bin/bash', '-lc', command],
-            { stdio: ['ignore', 'pipe', 'pipe'] }
+            { stdio: ['ignore', 'pipe', 'pipe'], env: ctx.dockerEnv }
         );
     } catch (e) {
         // spawn 同步抛错（如 dockerCmd 不存在）时必须释放锁，否则这个容器永远发不出消息
@@ -3952,6 +4108,190 @@ function sendHtml(res, statusCode, html, extraHeaders = {}) {
     res.end(html);
 }
 
+const SETUP_TEST_TIMEOUT_SECONDS = 60;
+const SETUP_TEST_PROMPT = 'Reply with the single word OK.';
+
+function getSetupWorkpath(state) {
+    return path.join(path.dirname(path.resolve(state.webConfigPath)), 'work');
+}
+
+async function inspectSetupImage(ctx, state) {
+    const image = `${ctx.imageName}:${ctx.imageVersion}`;
+    const pulling = state && state.imagePulls.get(image);
+    if (pulling) {
+        return { status: pulling.status, name: image, message: pulling.message };
+    }
+    const importing = ctx.importState();
+    if (importing.active) {
+        return { status: 'pulling', name: image, message: importing.message };
+    }
+    if (!ctx.runtimeState || ctx.runtimeState.status !== 'ready') {
+        return { status: 'unknown', name: image };
+    }
+    // 多个标签页同时轮询时共用同一次 inspect（只合并进行中的请求，不做时间缓存，镜像状态变化马上可见）
+    if (state && state.setupImageInflight && state.setupImageInflight.image === image) {
+        return state.setupImageInflight.promise;
+    }
+    const promise = isWebImagePresent(ctx, image).then(present => ({ status: present ? 'ready' : 'missing', name: image }));
+    if (!state) return promise;
+    state.setupImageInflight = { image, promise };
+    try {
+        return await promise;
+    } finally {
+        if (state.setupImageInflight && state.setupImageInflight.promise === promise) state.setupImageInflight = null;
+    }
+}
+
+// 在一次性容器里用所选 Agent 发一次最小请求；容器无论成败都会删除。
+async function runSetupConnectionTest(ctx, state, agent, envMap) {
+    const secrets = Object.values(envMap);
+    const image = await inspectSetupImage(ctx, state);
+    if (image.status !== 'ready') {
+        return { category: 'other', message: image.status === 'missing' ? `镜像 ${image.name} 尚未就绪，请等待准备完成后重试` : '容器环境尚未就绪，请稍后重试', detail: '' };
+    }
+
+    const spec = AGENT_ENV_SCHEMA[agent];
+    const template = deriveAgentPromptCommandFromDefaultCommand(resolveYoloCommand(spec.yolo));
+    if (!template) {
+        return { category: 'other', message: `${spec.label} 暂不支持连接测试`, detail: '' };
+    }
+    const agentCommand = renderAgentPromptCommand(template, SETUP_TEST_PROMPT);
+    const command = `timeout ${SETUP_TEST_TIMEOUT_SECONDS} /bin/bash -lc ${quoteBashSingleValue(agentCommand)}`;
+
+    const workpath = getSetupWorkpath(state);
+    fs.mkdirSync(workpath, { recursive: true });
+    const containerName = `manyoyo-setup-test-${crypto.randomBytes(4).toString('hex')}`;
+    const containerEnvs = [];
+    Object.entries(envMap).forEach(([key, value]) => containerEnvs.push('--env', `${key}=${value}`));
+    const args = buildContainerRunArgs({
+        containerName,
+        hostPath: workpath,
+        containerPath: '/workspace',
+        imageName: ctx.imageName,
+        imageVersion: ctx.imageVersion,
+        contModeArgs: [],
+        containerExtraArgs: [],
+        containerEnvs,
+        containerVolumes: [],
+        containerPorts: [],
+        defaultCommand: '/bin/bash'
+    });
+
+    try {
+        ctx.dockerExecArgs(args, { stdio: 'pipe' });
+        await ctx.waitForContainerReady(containerName, { throwOnFailure: true });
+        let timer;
+        const result = await Promise.race([
+            execCommandInWebContainer(ctx, containerName, command),
+            new Promise(resolve => {
+                timer = setTimeout(() => resolve({ exitCode: 124, output: '' }), (SETUP_TEST_TIMEOUT_SECONDS + 15) * 1000);
+            })
+        ]);
+        clearTimeout(timer);
+        return classifyConnectionResult(result, secrets);
+    } catch (e) {
+        return classifyConnectionResult({ exitCode: 1, output: e && e.message ? e.message : '' }, secrets);
+    } finally {
+        try {
+            ctx.dockerExecArgs(['rm', '-f', containerName], { stdio: 'pipe' });
+        } catch (e) {
+            // 容器可能根本没创建成功
+        }
+    }
+}
+
+// 网页只展示和“能不能用”相关的检查项，其余（端口、插件、模式、Agent 命令）对网页没有意义
+const WEB_DOCTOR_CODES = new Set([
+    'RUNTIME_AVAILABLE', 'RUNTIME_UNAVAILABLE', 'DAEMON_AVAILABLE', 'DAEMON_UNAVAILABLE',
+    'IMAGE_AVAILABLE', 'IMAGE_MISSING', 'CONFIG_AVAILABLE', 'CONFIG_MISSING'
+]);
+
+function sanitizeDoctorText(value) {
+    return redactSecrets(sanitizeServeLogText(String(value || ''))).slice(0, 500);
+}
+
+function buildWebDoctorReport(report) {
+    const checks = report.checks
+        .filter(check => WEB_DOCTOR_CODES.has(check.code))
+        .map(check => {
+            const item = {
+                code: check.code,
+                status: check.status,
+                summary: sanitizeDoctorText(check.summary),
+                action: sanitizeDoctorText(check.action),
+                // 通过项的 detail 是 info 的整段输出，只会带出本机路径和无关信息
+                detail: check.status === 'ok' ? '' : sanitizeDoctorText(check.detail)
+            };
+            if (check.fix) {
+                item.fix = {
+                    attempted: Boolean(check.fix.attempted),
+                    fixed: Boolean(check.fix.fixed),
+                    message: sanitizeDoctorText(check.fix.message)
+                };
+            }
+            return item;
+        });
+    return {
+        ok: !checks.some(check => check.status === 'error' && !(check.fix && check.fix.fixed)),
+        checks
+    };
+}
+
+async function buildSetupStatus(ctx, state) {
+    // 向导的“选择目录”与默认路径校验都要求目录已存在，所以展示默认路径前先建好
+    try { fs.mkdirSync(getSetupWorkpath(state), { recursive: true }); } catch (e) { /* 建不出来时由后续校验报错 */ }
+    // 向导的“选择目录”与默认路径校验都要求目录已存在，所以展示默认路径前先建好
+    try { fs.mkdirSync(getSetupWorkpath(state), { recursive: true }); } catch (e) { /* 建不出来时由后续校验报错 */ }
+    const snapshot = readWebConfigSnapshot(state.webConfigPath);
+    const config = snapshot.parseError ? {} : snapshot.parsed;
+    const configuredAgents = getConfiguredAgents(config);
+    return {
+        needsSetup: configuredAgents.length === 0,
+        configuredAgents,
+        serverUser: ctx.authUser,
+        // 自动生成（用户看不到）的密码不算“已设置”
+        passwordSet: !ctx.authPassAuto || (typeof config.serverPass === 'string' && config.serverPass !== ''),
+        configError: snapshot.parseError || null,
+        runtime: { status: ctx.runtimeState.status, message: ctx.runtimeState.message },
+        image: await inspectSetupImage(ctx, state),
+        defaultHostPath: getSetupWorkpath(state),
+        mirrors: readWebMirrors(state),
+        platform: process.platform,
+        runtimeKind: path.basename(String(ctx.dockerCmd || ''))
+    };
+}
+
+function resolveSetupRunInput(ctx, state, payload) {
+    const body = toPlainObject(payload);
+    const agent = String(body.agent || '').trim();
+    const snapshot = readWebConfigSnapshot(state.webConfigPath);
+    if (snapshot.parseError) {
+        const error = new Error('当前配置解析失败，无法继续');
+        error.detail = snapshot.parseError;
+        throw error;
+    }
+    const existingRun = toPlainObject(toPlainObject(snapshot.parsed.runs)[agent]);
+    let hostPath = '';
+    if (body.hostPath !== undefined && body.hostPath !== '') {
+        hostPath = typeof body.hostPath === 'string' ? body.hostPath.trim() : '';
+        if (!hostPath || !path.isAbsolute(hostPath)) {
+            throw new Error('hostPath 必须是绝对路径');
+        }
+        if (hostPath === getSetupWorkpath(state)) fs.mkdirSync(hostPath, { recursive: true });
+        ctx.validateHostPath(hostPath);
+    }
+    const profile = buildAgentRunProfile(agent, body.env === undefined ? {} : body.env, {
+        existingRun,
+        defaultHostPath: getSetupWorkpath(state),
+        hostPath
+    });
+    return { agent, snapshot, profile };
+}
+
+function redactLoginTokenInUrl(rawUrl) {
+    return String(rawUrl || '').replace(/([?&]token=)[^&#]*/gi, '$1[redacted]');
+}
+
 function sendRedirect(res, statusCode, location, extraHeaders = {}) {
     res.writeHead(statusCode, {
         Location: location,
@@ -4291,7 +4631,7 @@ function spawnWebTerminalProcess(ctx, containerName, cols, rows) {
         terminalBootstrap
     ];
 
-    return spawn(ctx.dockerCmd, dockerExecArgs, { stdio: ['pipe', 'pipe', 'pipe'] });
+    return spawn(ctx.dockerCmd, dockerExecArgs, { stdio: ['pipe', 'pipe', 'pipe'], env: ctx.dockerEnv });
 }
 
 function bindTerminalWebSocket(ctx, state, ws, containerName, cols, rows) {
@@ -4415,6 +4755,31 @@ function bindTerminalWebSocket(ctx, state, ws, containerName, cols, rows) {
     ws.on('error', cleanup);
 }
 
+const LOGIN_FREE_FAILURES = 5;
+const LOGIN_MAX_BACKOFF_SECONDS = 300;
+const LOGIN_FAILURE_TTL_MS = 15 * 60 * 1000;
+
+function getLoginRetryAfterSeconds(state, key, nowMs) {
+    const entry = state.loginFailures.get(key);
+    if (!entry || entry.blockedUntil <= nowMs) return 0;
+    return Math.max(1, Math.ceil((entry.blockedUntil - nowMs) / 1000));
+}
+
+// 前 5 次失败不限；之后每次失败把封禁时间翻倍（1、2、4…秒，上限 300 秒）；成功后清零
+function recordLoginFailure(state, key, nowMs) {
+    for (const [otherKey, entry] of state.loginFailures) {
+        if (nowMs - entry.lastAt > LOGIN_FAILURE_TTL_MS) state.loginFailures.delete(otherKey);
+    }
+    const entry = state.loginFailures.get(key) || { count: 0, blockedUntil: 0, lastAt: nowMs };
+    entry.count += 1;
+    entry.lastAt = nowMs;
+    if (entry.count > LOGIN_FREE_FAILURES) {
+        const seconds = Math.min(2 ** (entry.count - LOGIN_FREE_FAILURES - 1), LOGIN_MAX_BACKOFF_SECONDS);
+        entry.blockedUntil = nowMs + seconds * 1000;
+    }
+    state.loginFailures.set(key, entry);
+}
+
 async function handleWebAuthRoutes(req, res, pathname, ctx, state) {
     if (req.method === 'GET' && pathname === '/favicon.ico') {
         res.writeHead(204, { 'Cache-Control': 'no-store' });
@@ -4430,8 +4795,18 @@ async function handleWebAuthRoutes(req, res, pathname, ctx, state) {
     }
 
     // GET /auth/login 曾经是独立的登录页面，现在只留一个跳转，接住老书签
+    // 带 ?token= 时是本机启动器的一次性登录：仅回环监听启用，令牌用后即删
     if (req.method === 'GET' && pathname === '/auth/login') {
-        sendRedirect(res, 302, '/shadcn/auth/login');
+        const token = new URL(req.url || '/', 'http://localhost').searchParams.get('token');
+        if (token !== null && ctx.loginTokenDir && isLoopbackHost(ctx.serverHost) && consumeLoginToken(ctx.loginTokenDir, token)) {
+            const sessionId = createWebAuthSession(state, ctx.authUser);
+            sendRedirect(res, 302, '/', {
+                'Set-Cookie': getWebAuthCookie(sessionId),
+                'Referrer-Policy': 'no-referrer'
+            });
+            return true;
+        }
+        sendRedirect(res, 302, '/shadcn/auth/login', { 'Referrer-Policy': 'no-referrer' });
         return true;
     }
 
@@ -4445,12 +4820,23 @@ async function handleWebAuthRoutes(req, res, pathname, ctx, state) {
             return true;
         }
 
+        // 失败限速：按连接来源地址计数（不信任 X-Forwarded-For，伪造它就能绕过限速）；
+        // 反代后所有人共用一个来源，会被一起限速，这是有意的保守取舍
+        const rateKey = String(req.socket && req.socket.remoteAddress || '');
+        const retryAfter = getLoginRetryAfterSeconds(state, rateKey, ctx.nowMs());
+        if (retryAfter > 0) {
+            sendJson(res, 429, { error: `登录失败次数过多，请 ${retryAfter} 秒后重试` }, { 'Retry-After': String(retryAfter) });
+            return true;
+        }
+
         const userOk = secureStringEqual(username, ctx.authUser);
         const passOk = secureStringEqual(password, ctx.authPass);
         if (!(userOk && passOk)) {
+            recordLoginFailure(state, rateKey, ctx.nowMs());
             sendJson(res, 401, { error: '用户名或密码错误' });
             return true;
         }
+        state.loginFailures.delete(rateKey);
 
         const sessionId = createWebAuthSession(state, username);
         sendJson(
@@ -4661,8 +5047,7 @@ async function handleWebApi(req, res, pathname, ctx, state) {
                 }
 
                 const savePath = path.resolve(state.webConfigPath);
-                fs.mkdirSync(path.dirname(savePath), { recursive: true });
-                fs.writeFileSync(savePath, finalRaw, 'utf-8');
+                writeConfigFileSecure(savePath, finalRaw);
 
                 sendJson(res, 200, {
                     saved: true,
@@ -4671,6 +5056,223 @@ async function handleWebApi(req, res, pathname, ctx, state) {
                 });
             }
         },
+        {
+            method: 'GET',
+            match: currentPath => currentPath === '/api/setup/status' ? [] : null,
+            handler: async () => {
+                sendJson(res, 200, await buildSetupStatus(ctx, state));
+            }
+        },
+        {
+            method: 'GET',
+            match: currentPath => currentPath === '/api/setup/agents' ? [] : null,
+            handler: async () => {
+                sendJson(res, 200, { agents: listSetupAgents(), mirrorPresets: listMirrorPresets() });
+            }
+        },
+        {
+            method: 'POST',
+            match: currentPath => currentPath === '/api/setup/agent' ? [] : null,
+            handler: async () => {
+                const payload = await readJsonBody(req);
+                let input;
+                try {
+                    input = resolveSetupRunInput(ctx, state, payload);
+                } catch (e) {
+                    sendJson(res, 400, { error: e.message || '参数无效', detail: e.detail || '' });
+                    return;
+                }
+
+                let nextRaw;
+                try {
+                    nextRaw = buildAgentConfigRaw(baseRawOf(input.snapshot), input.agent, input.profile);
+                    parseAndValidateConfigRaw(nextRaw);
+                } catch (e) {
+                    sendJson(res, 400, { error: '配置写入失败', detail: e.message || '' });
+                    return;
+                }
+
+                const savePath = path.resolve(state.webConfigPath);
+                writeConfigFileSecure(savePath, nextRaw);
+                fs.mkdirSync(getSetupWorkpath(state), { recursive: true });
+
+                sendJson(res, 200, { saved: true, agent: input.agent, run: sanitizeSensitiveData(input.profile) });
+            }
+        },
+        {
+            method: 'POST',
+            match: currentPath => currentPath === '/api/setup/password' ? [] : null,
+            handler: async () => {
+                const payload = toPlainObject(await readJsonBody(req));
+                const reason = validateSetupPassword(payload.password);
+                if (reason) {
+                    sendJson(res, 400, { error: reason });
+                    return;
+                }
+                const snapshot = readWebConfigSnapshot(state.webConfigPath);
+                if (snapshot.parseError) {
+                    sendJson(res, 400, { error: '当前配置解析失败，无法继续', detail: snapshot.parseError });
+                    return;
+                }
+                let nextRaw;
+                try {
+                    nextRaw = buildPasswordConfigRaw(baseRawOf(snapshot), payload.password);
+                    parseAndValidateConfigRaw(nextRaw);
+                } catch (e) {
+                    sendJson(res, 400, { error: '配置写入失败' });
+                    return;
+                }
+                const savePath = path.resolve(state.webConfigPath);
+                writeConfigFileSecure(savePath, nextRaw);
+                // 就地生效：已登录会话保持有效，新登录用新密码；重启后配置里的 serverPass 优先于环境变量
+                ctx.authPass = payload.password;
+                ctx.authPassAuto = false;
+                sendJson(res, 200, { saved: true });
+            }
+        },
+        {
+            method: 'POST',
+            match: currentPath => currentPath === '/api/setup/mirrors' ? [] : null,
+            handler: async () => {
+                const payload = toPlainObject(await readJsonBody(req));
+                let mirrors;
+                try {
+                    mirrors = normalizeMirrors(payload.mirrors === undefined ? payload : payload.mirrors);
+                } catch (e) {
+                    sendJson(res, 400, { error: e.message || '软件源无效' });
+                    return;
+                }
+                const snapshot = readWebConfigSnapshot(state.webConfigPath);
+                if (snapshot.parseError) {
+                    sendJson(res, 400, { error: '当前配置解析失败，无法继续', detail: snapshot.parseError });
+                    return;
+                }
+                // 全部为官方默认且配置里本来没有 mirrors 时不写任何东西
+                if (!shouldWriteMirrors(snapshot.parsed, mirrors)) {
+                    sendJson(res, 200, { saved: false, mirrors });
+                    return;
+                }
+                let nextRaw;
+                try {
+                    nextRaw = buildMirrorsConfigRaw(baseRawOf(snapshot), mirrors);
+                    parseAndValidateConfigRaw(nextRaw);
+                } catch (e) {
+                    sendJson(res, 400, { error: '配置写入失败' });
+                    return;
+                }
+                writeConfigFileSecure(path.resolve(state.webConfigPath), nextRaw);
+                sendJson(res, 200, { saved: true, mirrors });
+            }
+        },
+        {
+            method: 'POST',
+            match: currentPath => currentPath === '/api/setup/test-connection' ? [] : null,
+            handler: async () => {
+                const payload = await readJsonBody(req);
+                let input;
+                try {
+                    input = resolveSetupRunInput(ctx, state, payload);
+                } catch (e) {
+                    sendJson(res, 400, { error: e.message || '参数无效', detail: e.detail || '' });
+                    return;
+                }
+                if (state.setupTestRunning) {
+                    sendJson(res, 409, { error: '已有连接测试正在进行，请稍后重试' });
+                    return;
+                }
+                state.setupTestRunning = true;
+                try {
+                    const result = await runSetupConnectionTest(ctx, state, input.agent, toPlainObject(input.profile.env));
+                    sendJson(res, 200, result);
+                } finally {
+                    state.setupTestRunning = false;
+                }
+            }
+        },
+        {
+            method: 'GET',
+            match: currentPath => currentPath === '/api/system/update' ? [] : null,
+            handler: async () => {
+                sendJson(res, 200, ctx.updateInfo());
+            }
+        },
+        {
+            method: 'POST',
+            match: currentPath => currentPath === '/api/system/runtime/retry' ? [] : null,
+            handler: async () => {
+                // 失败/超时后重新自愈；正在进行或已就绪时只返回当前状态，不重复启动
+                if (ctx.runtimeState.status === 'failed' && typeof ctx.retryRuntimeHeal === 'function') {
+                    ctx.retryRuntimeHeal();
+                    if (ctx.autoPullImage) startWebImagePrepare(ctx, state);
+                    startStaleSetupCleanup(ctx);
+                }
+                // 镜像拉取失败的条目会一直挂着：清掉后重新拉
+                if (ctx.runtimeState.status === 'ready' && ctx.autoPullImage) {
+                    let cleared = false;
+                    for (const [ref, entry] of state.imagePulls) {
+                        if (entry.status === 'failed') {
+                            state.imagePulls.delete(ref);
+                            cleared = true;
+                        }
+                    }
+                    if (cleared) startWebImagePrepare(ctx, state);
+                }
+                sendJson(res, 202, { status: ctx.runtimeState.status, message: ctx.runtimeState.message });
+            }
+        },
+        {
+            method: 'GET',
+            match: currentPath => currentPath === '/api/system/runtime' ? [] : null,
+            handler: async () => {
+                sendJson(res, 200, { status: ctx.runtimeState.status, message: ctx.runtimeState.message });
+            }
+        },
+        {
+            method: 'GET',
+            match: currentPath => currentPath === '/api/system/doctor' ? [] : null,
+            handler: async () => {
+                if (typeof ctx.doctorCheck !== 'function') {
+                    sendJson(res, 503, { error: '环境检查不可用' });
+                    return;
+                }
+                try {
+                    sendJson(res, 200, buildWebDoctorReport(await ctx.doctorCheck()));
+                } catch (e) {
+                    sendJson(res, 500, { error: '环境检查失败', detail: sanitizeDoctorText(e && e.message) });
+                }
+            }
+        },
+        {
+            method: 'POST',
+            match: currentPath => currentPath === '/api/system/doctor/fix' ? [] : null,
+            handler: async () => {
+                if (typeof ctx.doctorCheck !== 'function') {
+                    sendJson(res, 503, { error: '环境检查不可用' });
+                    return;
+                }
+                if (state.doctorFixRunning) {
+                    sendJson(res, 409, { error: '已有修复正在进行，请稍后重试' });
+                    return;
+                }
+                state.doctorFixRunning = true;
+                try {
+                    const report = await ctx.doctorCheck();
+                    const fixed = await applyDoctorFixes(report, {
+                        startRuntime: typeof ctx.doctorStartRuntime === 'function' ? ctx.doctorStartRuntime : undefined,
+                        pullImage: async () => {
+                            const imageRef = webImageRef(ctx);
+                            await ensureWebImage(ctx, state, imageRef);
+                            return { fixed: true, message: `已准备镜像 ${imageRef}` };
+                        }
+                    });
+                    sendJson(res, 200, buildWebDoctorReport(fixed));
+                } catch (e) {
+                    sendJson(res, 500, { error: '自动修复失败', detail: sanitizeDoctorText(e && e.message) });
+                } finally {
+                    state.doctorFixRunning = false;
+                }
+            }
+        },
         {
             method: 'GET',
             match: currentPath => currentPath === '/api/system/capacity' ? [] : null,
@@ -4742,8 +5344,7 @@ async function handleWebApi(req, res, pathname, ctx, state) {
                 }
 
                 const savePath = path.resolve(state.webConfigPath);
-                fs.mkdirSync(path.dirname(savePath), { recursive: true });
-                fs.writeFileSync(savePath, nextRaw, 'utf-8');
+                writeConfigFileSecure(savePath, nextRaw);
 
                 sendJson(res, 200, { saved: true, path: quickChatPath, run: quickChatRun });
             }
@@ -5745,6 +6346,15 @@ async function startWebServer(options) {
         authPassAuto: options.authPassAuto,
         serveTitle: typeof options.serveTitle === 'string' ? options.serveTitle : null,
         dockerCmd: options.dockerCmd,
+        dockerEnv: options.dockerEnv,
+        loginTokenDir: options.loginTokenDir || '',
+        doctorCheck: options.doctorCheck,
+        doctorStartRuntime: options.doctorStartRuntime,
+        runtimeState: options.runtimeState || { status: 'ready', message: '' },
+        autoPullImage: Boolean(options.autoPullImage),
+        // 离线安装器后台导入镜像的状态读取（默认没有导入）
+        updateInfo: typeof options.updateInfo === 'function' ? options.updateInfo : () => ({ enabled: false, installMode: 'unknown', current: '', latest: '', updateAvailable: false, checkedAt: null, error: '' }),
+        importState: typeof options.importState === 'function' ? options.importState : () => ({ active: false, message: '' }),
         hostPath: options.hostPath,
         containerPath: options.containerPath,
         imageName: options.imageName,
@@ -5764,6 +6374,9 @@ async function startWebServer(options) {
         getContainerStatus: options.getContainerStatus,
         waitForContainerReady: options.waitForContainerReady,
         dockerExecArgs: options.dockerExecArgs,
+        dockerExecAsync: options.dockerExecAsync,
+        nowMs: typeof options.nowMs === 'function' ? options.nowMs : Date.now,
+        retryRuntimeHeal: options.retryRuntimeHeal,
         showImagePullHint: options.showImagePullHint,
         removeContainer: options.removeContainer,
         logger: options.logger && typeof options.logger.info === 'function' ? options.logger : fallbackLogger,
@@ -5788,7 +6401,10 @@ async function startWebServer(options) {
         webConfigPath: options.webConfigPath || getDefaultWebConfigPath(),
         authSessions: new Map(),
         terminalSessions: new Map(),
-        agentRuns: new Map()
+        agentRuns: new Map(),
+        // imageRef -> { status: 'pulling'|'failed', message, promise }
+        imagePulls: new Map(),
+        loginFailures: new Map()
     };
 
     ensureWebHistoryDir(state.webHistoryDir);
@@ -5812,6 +6428,8 @@ async function startWebServer(options) {
     });
 
     const server = http.createServer(async (req, res) => {
+        // 身份标记：无参启动器复用实例前用它确认端口上跑的确实是 manyoyo serve（未登录的 401 也带）；不含任何版本或本机信息
+        res.setHeader('X-Manyoyo-Serve', '1');
         try {
             const fallbackHost = `${formatUrlHost(ctx.serverHost)}:${ctx.serverPort}`;
             const url = new URL(req.url, `http://${req.headers.host || fallbackHost}`);
@@ -5855,9 +6473,13 @@ async function startWebServer(options) {
 
             sendHtml(res, 404, '<h1>404 Not Found</h1>');
         } catch (e) {
+            if (e && e.imagePreparing) {
+                sendJson(res, 409, { error: e.message, imagePreparing: true });
+                return;
+            }
             ctx.logger.error('http request error', {
                 method: req && req.method ? req.method : '',
-                url: req && req.url ? req.url : '',
+                url: redactLoginTokenInUrl(req && req.url ? req.url : ''),
                 message: e && e.message ? e.message : 'Server Error'
             });
             if ((req.url || '').startsWith('/api/')) {
@@ -5995,6 +6617,11 @@ async function startWebServer(options) {
         });
     });
 
+    startStaleSetupCleanup(ctx);
+    if (ctx.autoPullImage) {
+        startWebImagePrepare(ctx, state);
+    }
+
     return {
         server,
         wsServer,