SillyTavern 服务端架构深度分析

// 1. 解析命令行参数
const cliArgs = new CommandLineParser().parse(process.argv);
globalThis.DATA_ROOT = cliArgs.dataRoot;
globalThis.COMMAND_LINE_ARGS = cliArgs;

// 2. 切换到服务器目录
process.chdir(serverDirectory);

// 3. 导入主模块
await import('./src/server-main.js');

// 1. 创建 Express 实例
const app = express();

// 2. 配置中间件链（详见第2节）
app.use(helmet({ contentSecurityPolicy: false }));
app.use(compression());
// ... 更多中间件

// 3. 路由分层注册
app.use('/api/users', usersPublicRouter);  // 公开 API
app.use(requireLoginMiddleware);            // 认证边界
app.use('/', userDataRouter);               // 私有 API

initUserStorage(dataRoot)
    .then(setDnsResolutionOrder)
    .then(ensurePublicDirectoriesExist)
    .then(migrateUserData)          // 数据迁移
    .then(migrateSystemPrompts)     // 系统提示词迁移
    .then(verifySecuritySettings)   // 安全验证
    .then(preSetupTasks)            // 插件加载等
    .then(apply404Middleware)
    .then(() => new ServerStartup(app, cliArgs).start())
    .then(postSetupTasks);

// Cookie Session 配置
app.use(cookieSession({
    name: getCookieSessionName(),        // session-{hostname_hash}
    sameSite: 'lax',
    httpOnly: true,
    maxAge: getSessionCookieAge(),       // 默认400天或配置值
    secret: getCookieSecret(dataRoot),   // 从文件读取或生成
}));

// CSRF 配置
const csrfSyncProtection = csrfSync({
    getTokenFromState: (req) => req.session.csrfToken,
    getTokenFromRequest: (req) => req.headers['x-csrf-token'],
    storeTokenInState: (req, token) => req.session.csrfToken = token,
    size: 32,
});

// Basic Auth (config.yaml 配置)
if (cliArgs.listen && cliArgs.basicAuthMode) {
    app.use(basicAuthMiddleware);
}

// IP 白名单
if (cliArgs.whitelistMode) {
    const whitelistMiddleware = await getWhitelistMiddleware();
    app.use(whitelistMiddleware);
}

// Host 白名单 (DNS Rebinding 防护)
app.use(hostWhitelistMiddleware);

POST /api/users/list       // 获取用户列表（支持 discreet 模式）
POST /api/users/login      // 用户登录（带速率限制）
POST /api/users/recover-step1  // 密码恢复第一步（发送验证码）
POST /api/users/recover-step2  // 密码恢复第二步（验证并重置密码）

// 旧端点 → 新端点 (308 永久重定向)
/createcharacter    → /api/characters/create
/renamecharacter    → /api/characters/rename
/editcharacter      → /api/characters/edit
/deletecharacter    → /api/characters/delete
/getcharacters      → /api/characters/all
/savechat           → /api/chats/save
/getchat            → /api/chats/get
// ... 更多重定向

// 支持配置方式：
// 1. config.yaml whitelist 数组
// 2. whitelist.txt 文件
// 3. Docker 主机自动解析

function isIPInWhitelist(whitelist, ip) {
    return whitelist.some(x => ipMatching.matches(ip, ipMatching.getMatch(x)));
}

// 处理 X-Real-IP / X-Forwarded-For 头
const enableForwardedWhitelist = getConfigValue('enableForwardedWhitelist', false);

const hostWhitelistEnabled = getConfigValue('hostWhitelist.enabled', false);
const hostWhitelist = getConfigValue('hostWhitelist.hosts', []);
const hostWhitelistScan = getConfigValue('hostWhitelist.scan', false);

// 扫描模式：记录未授权 Host，但不阻止
// 启用模式：严格验证 Host 头

const usePerUserAuth = PER_USER_BASIC_AUTH && ENABLE_ACCOUNTS;

if (!usePerUserAuth && username === basicAuthUserName && password === basicAuthUserPassword) {
    return callback();  // 全局认证通过
} else if (usePerUserAuth) {
    // 验证用户名对应用户密码
    for (const userHandle of userHandles) {
        if (username === userHandle) {
            const user = await storage.getItem(toKey(userHandle));
            if (user && user.enabled && user.password === getPasswordHash(password, user.salt)) {
                return callback();
            }
        }
    }
}

// Token 生成与验证流程
1. 客户端请求 GET /csrf-token
2. 服务端生成 token，存入 req.session.csrfToken
3. 客户端后续请求携带 x-csrf-token header
4. 服务端验证：req.session.csrfToken === req.headers['x-csrf-token']

// 禁用方式：--disableCsrf 命令行参数
// 禁用时返回固定 token: 'disabled'

export async function verifySecuritySettings() {
    // 监听模式安全检查
    if (!listen) return;  // localhost 模式跳过
    
    // 强制安全配置检查
    if (!ENABLE_ACCOUNTS) {
        logSecurityAlert('Enable whitelisting, basic authentication or user accounts.');
    }
    
    // 用户密码检查
    const unprotectedUsers = users.filter(x => !x.password);
    const unprotectedAdminUsers = unprotectedUsers.filter(x => x.admin);
    
    if (unprotectedAdminUsers.length > 0) {
        logSecurityAlert('Set a password for all admin users.');
    }
}

// 1. 单用户无密码自动登录
async function singleUserLogin(request) {
    if (userHandles.length === 1) {
        const user = await storage.getItem(toKey(userHandles[0]));
        if (user && !user.password) {
            request.session.handle = userHandles[0];
            return true;
        }
    }
}

// 2. Authelia SSO 登录
async function autheliaUserLogin(request) {
    return headerUserLogin(request, 'Remote-User');
}

// 3. Authentik SSO 登录
async function authentikUserLogin(request) {
    return headerUserLogin(request, 'X-Authentik-Username');
}

// 4. Per-User Basic Auth 登录
async function basicUserLogin(request) {
    // 从 Authorization header 提取用户名
    // 验证密码后自动登录
}

export async function setUserDataMiddleware(request, response, next) {
    // 禁用用户系统时使用默认用户
    if (!ENABLE_ACCOUNTS) {
        request.user = {
            profile: DEFAULT_USER,
            directories: getUserDirectories(DEFAULT_USER.handle),
        };
        return next();
    }

    // 从会话获取用户
    const handle = request.session?.handle;
    if (!handle) return next();

    const user = await storage.getItem(toKey(handle));
    if (!user || !user.enabled) return next();

    request.user = {
        profile: user,
        directories: getUserDirectories(handle),
    };
    
    // 首页访问刷新会话
    if (request.method === 'GET' && request.path === '/') {
        request.session.touch = Date.now();
    }
    
    next();
}

// users.js 中的 Router 提供用户数据文件服务
export const router = express.Router();

router.use('/backgrounds/*', createRouteHandler(req => req.user.directories.backgrounds));
router.use('/characters/*', createRouteHandler(req => req.user.directories.characters));
router.use('/User%20Avatars/*', createRouteHandler(req => req.user.directories.avatars));
router.use('/assets/*', createRouteHandler(req => req.user.directories.assets));
router.use('/user/images/*', createRouteHandler(req => req.user.directories.userImages));
router.use('/scripts/extensions/third-party/*', createExtensionsRouteHandler(req => req.user.directories.extensions));