Skip to content

k.history ​

站点版本历史查询、差异对比、回滚与远程站点日志查看

适用上下文前置条件典型用途
Api / CodeBlock / <script env="server">本地方法(除 videoLog(versionId) 外)均需已登录同组织平台账号审计编辑日志、对比历史差异、回滚误操作或远程查日志

登录与组织权限前提

除单参本地 videoLog(versionId) 外,其余本地历史方法均要求当前请求已通过 k.account 登录且用户所属组织与站点一致,否则直接抛出 "An authenticated user is required"。

快速上手 ​

js
k.api.get("history-recent", () => {
    if (!k.account.isLogin) {
        k.response.statusCode(401)
        return { error: "Authentication required" }
    }

    const page = k.history.list(10)
    return {
        totalCount: page.totalCount,
        items: page.list
    }
})

方法速查 ​

方法 / 属性说明返回值
k.history.list(top) / list(query)读取最近站点操作日志(脚本内请传数字 top)SiteLogPage
k.history.get(logId)根据日志 ID 获取单条本地操作日志详情SiteLogItem
k.history.versions(logId) / (nameOrId, storeName?, tableName?)查询同一对象的所有本地历史版本SiteLogVersion[]
k.history.compare(id) / compare(id1, id2)对比对象当前版本或任意两个历史版本的差异VersionCompareViewModel
k.history.videoLog(versionId)读取指定版本的编辑器操作录制视频 JSONstring | null
k.history.undo(logId)撤销单条本地 CMS 变更记录boolean
k.history.undoMany(logIds)批量撤销本地变更记录(单次上限 1,000 条)boolean
k.history.restoreTo(logId) / restoreTo(time)将当前站点回退到指定历史日志点或时间点number
k.history.checkOut(options)基于历史快照在当前组织检出创建新站点SiteCheckoutResult
k.history.lastLog(pageIndex, pagesize, siteUrl)分页获取指定 siteUrl 远程站点的日志摘要RemoteLastLogResult
k.history.versions(keyHash, storeHash, tableHash, siteUrl)查询远程站点指定对象的历史版本列表ItemVersionViewModel[]
k.history.compare(id1, id2, siteUrl)对比远程站点对象的两个版本差异VersionCompareViewModel
k.history.videoLog(versionId, siteUrl)读取远程站点指定版本的录制视频 JSONstring

概述 ​

k.history 提供当前站点 CMS 编辑历史与版本记录的脚本访问能力,支持查询日志列表、查看对象历史版本、对比版本差异、回放编辑录制视频、撤销/还原更改、将历史版本检出为新站点,以及查询远程站点的只读历史记录。k.site.editLog 与 k.history 指向同一能力入口,提供完全一致的方法与数据。

分类方法说明
只读历史查询list、get、versions、compare、videoLog查询本地操作日志、对象历史版本、文本/图片差异与操作回放
破坏性回滚与检出undo、undoMany、restoreTo、checkOut撤销指定更改、将站点还原到历史时间点或检出为新站点
远程站点历史与对比lastLog、versions(4 参)、compare(3 参)、videoLog(2 参)查询并对比指定 siteUrl 远程站点的操作历史与录制视频

只读历史查询 ​

list() ​

分页读取当前站点最近的操作日志列表,支持两种重载签名:

  1. 数值上限:k.history.list(top) 读取最近 top 条日志(pageNr 固定为 1;top <= 0 时默认为 50,最大截断为 200)。
  2. 结构化查询:k.history.list(query) 对应类型定义中的 SiteLogQuery 筛选签名。

脚本传参重载行为说明

在脚本运行时中,直接向 k.history.list(...) 传入普通 JavaScript 对象字面量(如 { pageNr: 1, pageSize: 5, storeName: "Code" })会优先匹配到数值重载 list(top) 并被按 top = 0 处理,导致返回未过滤的最近 50 条日志(pageSize: 50)且筛选条件不会生效。在站点脚本中,请直接调用 k.history.list(top)(最多 200 条),再按 storeName、actionType 或 itemName 在脚本数组上过滤。

参数(list(top)):

参数类型必填默认值说明
topnumber是-读取最新日志条数(<= 0 时回退为 50,上限 200)

返回: SiteLogPage。

js
k.api.get("history-recent", () => {
    if (!k.account.isLogin) {
        k.response.statusCode(401)
        return { error: "Authentication required" }
    }

    const page = k.history.list(10)
    const codeLogs = page.list.filter((item) => item.storeName === "Code")

    return {
        totalCount: page.totalCount,
        pageSize: page.pageSize,
        totalPages: page.totalPages,
        recentItems: page.list,
        recentCodeLogs: codeLogs
    }
})

get() ​

根据日志 ID 获取单条本地操作日志详情。

参数:

参数类型必填说明
logIdnumber是正整数日志 ID;不存在或非正数时抛出异常

返回: SiteLogItem。

js
k.api.get("history-detail", () => {
    if (!k.account.isLogin) {
        k.response.statusCode(401)
        return { error: "Authentication required" }
    }

    const recent = k.history.list(1)
    if (recent.list.length === 0) {
        return { item: null }
    }

    const detail = k.history.get(recent.list[0].id)
    return { detail: detail }
})

versions() ​

查询同一对象的所有历史版本记录,支持按日志 ID 或按对象名称/ID 查询:

  1. 按日志 ID:k.history.versions(logId) 根据某条日志 ID 反查该对象的所有历史版本(按时间倒序)。
  2. 按对象标识:k.history.versions(nameOrId, storeName, tableName) 按对象名称或 GUID 查询版本历史。storeName(如 "Page"、"View"、"Layout"、"Code"、"HtmlBlock"、"Label")与 tableName(动态数据表名)必须二选一,不能同时提供或同时省略。

已删除对象的查询提示

若查询的 CMS 资源已被删除且不按名称固定映射 ID(如 Page、View、Code),按名称查询会抛出找不到对象的异常,此时请改传对象的 GUID 字符串作为 nameOrId。

参数:

参数类型必填说明
logIdnumber是(重载 1)任意一条所属对象的日志 ID
nameOrIdstring是(重载 2)对象名称或 GUID
storeNamestring否(与 tableName 二选一)CMS 存储类型名(如 "Code"、"Page")
tableNamestring否(与 storeName 二选一)动态数据表名

返回: SiteLogVersion[]。

js
k.api.get("history-versions", () => {
    if (!k.account.isLogin) {
        k.response.statusCode(401)
        return { error: "Authentication required" }
    }

    const recent = k.history.list(10)
    const target = recent.list.find((item) => item.storeName !== "Table" && item.itemName)
    if (!target) {
        return { versions: [] }
    }

    const byLogId = k.history.versions(target.id)
    const byName = k.history.versions(target.itemName, target.storeName)

    return {
        itemName: target.itemName,
        storeName: target.storeName,
        byLogId: byLogId,
        sameCount: byLogId.length === byName.length
    }
})

compare() ​

对比对象历史版本的内容差异,支持两种重载:

  1. 与最新版对比:k.history.compare(id) 将日志版本 id 与同一对象的最新版本进行对比。
  2. 任意两版本对比:k.history.compare(id1, id2) 对比同一对象的任意两个历史版本;当 id1 > id2 时系统会自动对调顺序,使旧版本在左(id1 / title1 / source1)、新版本在右(id2 / title2 / source2)。

dataType 运行时返回类型

智能提示将 dataType 标注为 'String' | 'Image',在运行时 JSON 序列化结果中该枚举返回数值:0 表示文本对比(String),1 表示图片对比(Image)。

参数:

参数类型必填说明
id / id1number是第一个正整数日志版本 ID
id2number否第二个正整数日志版本 ID(省略时默认对比当前最新版本)

返回: VersionCompareViewModel。

js
k.api.get("history-compare", () => {
    if (!k.account.isLogin) {
        k.response.statusCode(401)
        return { error: "Authentication required" }
    }

    const recent = k.history.list(50)
    for (const item of recent.list) {
        if (item.storeName === "Table") continue
        const versions = k.history.versions(item.id)
        if (versions.length >= 2) {
            return {
                withLatest: k.history.compare(versions[versions.length - 1].id),
                twoVersions: k.history.compare(versions[1].id, versions[0].id)
            }
        }
    }

    return { message: "No object with multiple versions found" }
})

videoLog() ​

读取指定版本 ID 对应的编辑器操作录制视频 JSON 数据;若该版本没有录制视频数据,则返回 null。

参数:

参数类型必填说明
versionIdnumber是版本日志 ID

返回: string | null。

js
k.api.get("history-video", () => {
    const versionId = Number(k.request.queryString.get("versionId") || 0)
    if (!versionId) {
        return { video: null }
    }

    const video = k.history.videoLog(versionId)
    return {
        hasVideo: typeof video === "string" && video.length > 0,
        video: video
    }
})

破坏性回滚与检出 ​

不可逆变更与站点创建风险

以下方法会直接修改线上站点内容、重写多条资源记录或在当前组织下创建全新站点,且回滚操作本身会生成新的操作日志:

  • 仅在已验证目标 logId、具备组织管理员/编辑确认机制且确认授权的情况下调用;
  • undoMany() 单次最多支持 1,000 个日志 ID;
  • restoreTo() 与 checkOut() 最多允许跨越目标日志点之后的 99,999 条后续日志;
  • 不要在未鉴权的匿名接口中暴露这些方法。

undo() ​

撤销单条本地 CMS 变更记录,回滚后系统会生成一条新的操作日志。

参数:

参数类型必填说明
logIdnumber是要撤销的正整数日志 ID(非正数或不存在时抛出异常)

返回: boolean(成功时返回 true)。

undoMany() ​

批量撤销多条本地 CMS 变更记录。系统会在修改任何数据前先校验全部 logIds 是否存在,去重后按批回滚。

参数:

参数类型必填说明
logIdsnumber[]是非空正整数日志 ID 数组,单次最多 1,000 条

返回: boolean(成功时返回 true)。

restoreTo() ​

将当前站点整体状态回退到指定历史日志 ID 或时间点(UTC Date),系统会写入新的还原日志记录。

参数:

参数类型必填说明
logIdnumber是(重载 1)目标历史日志 ID(其后日志数不得超过 99,999)
timeDate是(重载 2)目标时间点(恢复到不晚于该时间的最后一条日志;若不存在匹配日志则抛出异常)

返回: number(实际还原到的目标日志 ID)。

checkOut() ​

基于指定历史日志 ID 的站点快照,在当前组织下创建一个全新独立站点并绑定域名;若过程中发生异常,系统会自动清理并删除新建的临时站点。

参数:

参数类型必填说明
optionsSiteCheckoutOptions是检出站点配置对象
options.logIdnumber是目标历史日志 ID(其后日志数不得超过 99,999)
options.siteNamestring是新站点名称(在当前组织下必须可用)
options.fullDomainstring是新站点绑定的完整域名(全局未占用)
options.publishedboolean是创建完成后是否将新站点设为已发布状态

返回: SiteCheckoutResult。

远程站点历史与对比 ​

以下四个方法通过 HTTP 请求指定 siteUrl 站点的远程日志接口,并自动透传当前请求中的 Cookie 与 Authorization 请求头(完整 TypeScript 签名见文末定义):

  • k.history.lastLog(pageIndex, pagesize, siteUrl)
  • k.history.versions(keyHash, storeNameHash, tableNameHash, siteUrl)
  • k.history.compare(id1, id2, siteUrl)
  • k.history.videoLog(versionId, siteUrl)

siteUrl 格式要求

传入 siteUrl 时请不要保留末尾斜杠 /(例如传入 "https://example.com" 或使用 k.site.info.baseUrl.replace(/\/+$/, ""))。带有末尾 / 时拼接出的远程路径会出现双斜杠,导致返回字段全为 null。

参数:

方法参数说明
lastLog(pageIndex, pagesize, siteUrl)pageIndex: number、pagesize: number、siteUrl: string获取远程站点分页日志摘要
versions(keyHash, storeNameHash, tableNameHash, siteUrl)keyHash: string、storeNameHash: number、tableNameHash: number、siteUrl: string按日志条目里的 keyHash 与存储/表哈希获取远程对象版本列表
compare(id1, id2, siteUrl)id1: number、id2: number、siteUrl: string对比远程站点对象的两个版本 ID
videoLog(versionId, siteUrl)versionId: number、siteUrl: string读取远程站点指定版本的录制视频 JSON

示例:

js
k.api.get("history-remote", () => {
    const siteUrl = k.site.info.baseUrl.replace(/\/+$/, "")
    const remotePage = k.history.lastLog(1, 5, siteUrl)
    const first = remotePage.list.length > 0 ? remotePage.list[0] : null
    if (!first) {
        return { totalCount: remotePage.totalCount, items: [] }
    }

    const remoteVersions = k.history.versions(
        String(first.keyHash),
        first.storeNameHash,
        first.tableNameHash,
        siteUrl
    )
    const diff = remoteVersions.length >= 2
        ? k.history.compare(remoteVersions[1].id, remoteVersions[0].id, siteUrl)
        : null
    const video = k.history.videoLog(first.id, siteUrl)

    return {
        totalCount: remotePage.totalCount,
        firstId: first.id,
        versionsCount: remoteVersions.length,
        hasVideo: typeof video === "string" && video.length > 0,
        diff: diff
    }
})

TypeScript 定义 ​

展开完整 TypeScript 定义
ts
interface KEditLog {
  // 只读历史查询
  list(top: number): SiteLogPage;
  list(query: SiteLogQuery): SiteLogPage;
  get(logId: number): SiteLogItem;
  versions(logId: number): SiteLogVersion[];
  versions(nameOrId: string, storeName?: string, tableName?: string): SiteLogVersion[];
  compare(id: number): VersionCompareViewModel;
  compare(id1: number, id2: number): VersionCompareViewModel;
  videoLog(versionId: number): string;

  // 破坏性回滚与检出
  undo(logId: number): boolean;
  undoMany(logIds: number[]): boolean;
  restoreTo(logId: number): number;
  restoreTo(time: Date): number;
  checkOut(options: SiteCheckoutOptions): SiteCheckoutResult;

  // 远程站点历史与对比
  lastLog(pageIndex: number, pagesize: number, siteUrl: string): RemoteLastLogResult;
  videoLog(versionId: number, siteUrl: string): string;
  versions(keyHash: string, storeNameHash: number, tableNameHash: number, siteUrl: string): ItemVersionViewModel[];
  compare(id1: number, id2: number, siteUrl: string): VersionCompareViewModel;
}

interface SiteLogPage {
  list: SiteLogItem[];
  totalCount: number;
  pageNr: number;
  pageSize: number;
  totalPages: number;
}

interface SiteLogQuery {
  pageNr: number;
  pageSize: number;
  actionType: string; // "Add" | "Update" | "Delete"
  storeName: string;
  tableName: string;
  name: string;
  userId?: any;
  startDate?: Date;
  endDate?: Date;
}

interface SiteLogItem {
  id: number;
  lastModified: Date;
  timeTick: number;
  userId: any;
  userName: string;
  itemName: string;
  storeName: string;
  keyHash: any;
  storeNameHash: number;
  tableNameHash: number;
  tableName: string;
  actionType: string;
  isAI: boolean;
  hasVideo: boolean;
}

interface SiteLogVersion {
  id: number;
  lastModified: Date;
  userId: any;
  userName: string;
  actionType: string;
  isAI: boolean;
  hasVideo: boolean;
}

type VersionDataType = "String" | "Image";

interface VersionCompareViewModel {
  title1: string;
  title2: string;
  objectId: any;
  constType: number;
  id1: number;
  id2: number;
  source1: string;
  source2: string;
  dataType: VersionDataType;
}

interface SiteCheckoutOptions {
  logId: number;
  siteName: string;
  fullDomain: string;
  published: boolean;
}

interface SiteCheckoutResult {
  siteId: any;
  siteName: string;
  fullDomain: string;
  published: boolean;
}

interface RemoteLastLogResult {
  list: SiteLogViewModel[];
  totalCount: number;
  pageNr: number;
  pageSize: number;
  totalPages: number;
}

interface SiteLogViewModel {
  id: number;
  lastModified: Date;
  userName: string;
  itemName: string;
  storeName: string;
  keyHash: any;
  storeNameHash: number;
  tableNameHash: number;
  tableName: string;
  actionType: string;
  hasVideo: boolean;
}

interface ItemVersionViewModel {
  id: number;
  lastModified: Date;
  userName: string;
  hasVideo: boolean;
}

相关文档 ​

  • k.site — 当前站点结构化资源访问(k.site.editLog 为 k.history 的同功能入口)
  • k.account.login — 平台用户登录与会话鉴权
  • 操作日志(后台) — 后台版本管理、Diff 对比与视频回放界面说明