k.history
站点版本历史查询、差异对比、回滚与远程站点日志查看
| 适用上下文 | 前置条件 | 典型用途 |
|---|---|---|
Api / CodeBlock / <script env="server"> | 本地方法(除 videoLog(versionId) 外)均需已登录同组织平台账号 | 审计编辑日志、对比历史差异、回滚误操作或远程查日志 |
登录与组织权限前提
除单参本地 videoLog(versionId) 外,其余本地历史方法均要求当前请求已通过 k.account 登录且用户所属组织与站点一致,否则直接抛出 "An authenticated user is required"。
快速上手
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) | 读取指定版本的编辑器操作录制视频 JSON | string | 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) | 读取远程站点指定版本的录制视频 JSON | string |
概述
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()
分页读取当前站点最近的操作日志列表,支持两种重载签名:
- 数值上限:
k.history.list(top)读取最近top条日志(pageNr固定为1;top <= 0时默认为50,最大截断为200)。 - 结构化查询:
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)):
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
top | number | 是 | - | 读取最新日志条数(<= 0 时回退为 50,上限 200) |
返回: SiteLogPage。
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 获取单条本地操作日志详情。
参数:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
logId | number | 是 | 正整数日志 ID;不存在或非正数时抛出异常 |
返回: SiteLogItem。
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 查询:
- 按日志 ID:
k.history.versions(logId)根据某条日志 ID 反查该对象的所有历史版本(按时间倒序)。 - 按对象标识:
k.history.versions(nameOrId, storeName, tableName)按对象名称或 GUID 查询版本历史。storeName(如"Page"、"View"、"Layout"、"Code"、"HtmlBlock"、"Label")与tableName(动态数据表名)必须二选一,不能同时提供或同时省略。
已删除对象的查询提示
若查询的 CMS 资源已被删除且不按名称固定映射 ID(如 Page、View、Code),按名称查询会抛出找不到对象的异常,此时请改传对象的 GUID 字符串作为 nameOrId。
参数:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
logId | number | 是(重载 1) | 任意一条所属对象的日志 ID |
nameOrId | string | 是(重载 2) | 对象名称或 GUID |
storeName | string | 否(与 tableName 二选一) | CMS 存储类型名(如 "Code"、"Page") |
tableName | string | 否(与 storeName 二选一) | 动态数据表名 |
返回: SiteLogVersion[]。
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()
对比对象历史版本的内容差异,支持两种重载:
- 与最新版对比:
k.history.compare(id)将日志版本id与同一对象的最新版本进行对比。 - 任意两版本对比:
k.history.compare(id1, id2)对比同一对象的任意两个历史版本;当id1 > id2时系统会自动对调顺序,使旧版本在左(id1/title1/source1)、新版本在右(id2/title2/source2)。
dataType 运行时返回类型
智能提示将 dataType 标注为 'String' | 'Image',在运行时 JSON 序列化结果中该枚举返回数值:0 表示文本对比(String),1 表示图片对比(Image)。
参数:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
id / id1 | number | 是 | 第一个正整数日志版本 ID |
id2 | number | 否 | 第二个正整数日志版本 ID(省略时默认对比当前最新版本) |
返回: VersionCompareViewModel。
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。
参数:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
versionId | number | 是 | 版本日志 ID |
返回: string | null。
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 变更记录,回滚后系统会生成一条新的操作日志。
参数:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
logId | number | 是 | 要撤销的正整数日志 ID(非正数或不存在时抛出异常) |
返回: boolean(成功时返回 true)。
undoMany()
批量撤销多条本地 CMS 变更记录。系统会在修改任何数据前先校验全部 logIds 是否存在,去重后按批回滚。
参数:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
logIds | number[] | 是 | 非空正整数日志 ID 数组,单次最多 1,000 条 |
返回: boolean(成功时返回 true)。
restoreTo()
将当前站点整体状态回退到指定历史日志 ID 或时间点(UTC Date),系统会写入新的还原日志记录。
参数:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
logId | number | 是(重载 1) | 目标历史日志 ID(其后日志数不得超过 99,999) |
time | Date | 是(重载 2) | 目标时间点(恢复到不晚于该时间的最后一条日志;若不存在匹配日志则抛出异常) |
返回: number(实际还原到的目标日志 ID)。
checkOut()
基于指定历史日志 ID 的站点快照,在当前组织下创建一个全新独立站点并绑定域名;若过程中发生异常,系统会自动清理并删除新建的临时站点。
参数:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
options | SiteCheckoutOptions | 是 | 检出站点配置对象 |
options.logId | number | 是 | 目标历史日志 ID(其后日志数不得超过 99,999) |
options.siteName | string | 是 | 新站点名称(在当前组织下必须可用) |
options.fullDomain | string | 是 | 新站点绑定的完整域名(全局未占用) |
options.published | boolean | 是 | 创建完成后是否将新站点设为已发布状态 |
返回: 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 |
示例:
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 定义
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 对比与视频回放界面说明