JCAlways Hexo https://blog.zhangsifan.com/ All rights reserved 2026, JCAlways 前端开发与编程技术笔记 | 张思帆的博客 JCAlways 2025-10-10T16:00:00.000Z JCAlways 前端使用

OnlyOffice 文档服务器（Document Server）提供了前端 SDK，通过简单的 DocsAPI.DocEditor 即可在网页中嵌入在线文档的查看与编辑功能。整体流程分三步：

  1. 引入 SDK：在页面中加载文档服务器提供的 api.js（注意域名需替换为你的 OnlyOffice 服务地址）
  2. 配置 config 对象：声明文档信息（document）、编辑配置（editorConfig）与事件回调（events）
  3. 实例化编辑器：new DocsAPI.DocEditor(容器id, config) 将编辑器挂载到指定 DOM 中
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>OnlyOffice</title>
    <style>
      html,
      body {
        padding: 0;
        margin: 0;
      }
    </style>
  </head>
  <body>
    <script
      type="text/javascript"
      src="https://example.com/web-apps/apps/api/documents/api.js"
    ></script>
    <div id="preview"></div>
    <script type="module">
      let config = {
        document: {
          documentType: 'text',
          width: '100%', //打开窗口宽度
          height: '100%', //打开窗口高度
          fileType: fileType, //文档类型
          key: key, //定义用于服务识别文档的唯一文档标识符。每次编辑和保存文档时，都必须重新生成密钥。长度限制为128个符号。
          title: title, //为查看或编辑的文档定义所需的文件名，该文件名也将在下载文档时用作文件名。长度限制为128个符号。
          url: url, //定义存储原始查看或编辑的文档的绝对URL
          info: {
            owner: '', //文件创建者名称
            sharingSettings: [
              //文件对应用户的操作权限配置
              {
                permissions: 'Full Access', // 完全操作权限-Full Access,只读权限-Read Only 拒绝访问-Deny Access
                user: '', //有次权限的用户
              },
              {
                permissions: 'Read Only',
                user: '',
              },
            ],
            uploaded: '', //文件创建时间
          },
          //文档权限参数
          permissions: {
            edit: true, //（文件是否可以编辑，false时文件不可编辑）
            fillForms: true, //定义是否能在文档中填充表单
            print: true, //定义文档是否能打印
            review: false, //第一是否显示审阅文档菜单
            comment: true, //定义是否可以注释文档。如果注释权限设置为“ true”，则文档侧栏将包含“注释”菜单选项；只有将mode参数设置为edit时才生效，默认值与edit参数的值一致。
            copy: true, //是否允许您将内容复制到剪贴板。默认值为true。
            download: true, //定义是否可以下载文档或仅在线查看或编辑文档。如果下载权限设置为“false”下载为菜单选项将没有。默认值为true。
            modifyContentControl: true, //定义是否可以更改内容控件设置。仅当mode参数设置为edit时，内容控件修改才可用于文档编辑器。默认值为true。
            modifyFilter: true, //定义过滤器是否可以全局应用（true）影响所有其他用户，或局部应用（false），即仅适用于当前用户。如果将mode参数设置为edit，则过滤器修改仅对电子表格编辑器可用。默认值为true。
          },
        },
        // type: "embedded",
        //打开文档类型
        // text对应各种文档类型(.doc, .docm, .docx, .dot, .dotm, .dotx, .epub, .fodt, .htm, .html, .mht, .odt, .ott, .pdf, .rtf, .txt, .djvu, .xps)
        //spreadsheet对应表格类型(.csv, .fods, .ods, .ots, .xls, .xlsm, .xlsx, .xlt, .xltm, .xltx)
        //presentation对应PPT类型(.fodp, .odp, .otp, .pot, .potm, .potx, .pps, .ppsm, .ppsx, .ppt, .pptm, .pptx)
        editorConfig: {
          //编辑配置
          createUrl: 'http://docServer:port/url-to-create-document/', //指定创建文件的页面,添加该配置后文档服务器插件才会显示新建文件按钮
          mode: model, //文档操作模式 view 视图模式不可编辑  edit 编辑模式可编辑文档
          callbackUrl: callbackUrl, //保存文件时的回调地址
          lang: 'zh-CN', //语言环境
          customization: {
            //定制部分允许自定义编辑器界面，使其看起来像您的其他产品，并更改是否存在其他按钮，链接，更改徽标和编辑者所有者详细信息。
            help: false, //定义是显示还是隐藏“帮助”菜单按钮。默认值为true。
            hideRightMenu: false, //定义在第一次加载时是显示还是隐藏右侧菜单。默认值为false。
            autosave: false, //定义是启用还是禁用“自动保存”菜单选项。请注意，如果您在菜单中更改此选项，它将被保存到浏览器的localStorage中。默认值为true。
            forcesave: true, //定义保存按钮是否显示默认false
            chat: false, //定义“聊天”菜单按钮是显示还是隐藏；请注意，如果您隐藏“聊天”按钮，则相应的聊天功能也将被禁用。默认值为true。
            commentAuthorOnly: false, //定义用户是否只能编辑和删除他的评论。默认值为false。
            comments: false, //定义是显示还是隐藏“注释”菜单按钮；请注意，如果您隐藏“评论”按钮，则相应的评论功能将仅可用于查看，评论的添加和编辑将不可用。默认值为true。
            compactHeader: false, //定义是否将菜单栏放在在徽标旁边使界面更加紧凑默认false。
            compactToolbar: false, //定义显示的顶部工具栏类型是完整（false）还是紧凑true。默认值为false 多余菜单将在右侧折叠点击显示。
            compatibleFeatures: false, //定义仅与OOXML格式兼容的功能的使用。例如，不要在整个文档上使用注释。默认值为false。
            macros: false, //定义是否将运行文档宏以及可用的宏设置。默认值为true。
            macrosMode: 'warn', //定义是否将运行文档宏。可以采用以下值： disable -根本不运行；enable -自动运行所有宏；warn -警告宏并请求允许运行。默认值为original。
            plugins: false, //定义是否将启动插件并可用。默认值为true。
            showReviewChanges: false, //定义在加载编辑器时是否自动显示或隐藏审阅更改面板。默认值为false。
            spellcheck: false, //定义在加载编辑器时是否自动打开或关闭拼写检查器。拼写检查器仅适用于文档编辑器和演示文稿编辑器。默认值为true。
            toolbarNoTabs: false, //定义是突出显示顶部工具栏选项卡样式。默认值为false。
            unit: 'cm', //定义在标尺和对话框中使用的度量单位。可以采用以下值：cm -厘米，pt-点，inch -英寸。默认值为厘米（cm）。
            zoom: 100, //定义以百分比为单位的文档显示缩放值。可以取大于0的值。对于文本文档和演示文稿，可以将此参数设置为-1（使文档适合页面选项）或-2（使文档页面宽度适合编辑器页面）。默认值为100。
            customer: {
              //关于 文档编辑器的显示信息
              address: 'My City, 123a-45', //有权访问编辑或编辑作者的公司或个人的邮政地址，
              info: 'Some additional information', //有关您希望其他人认识的公司或个人的一些其他信息，
              logo: 'https://example.com/logo-big.png', //图片徽标的路径（此文件没有特别建议，但是如果使用透明背景的.png格式会更好）。图片必须具有以下尺寸：432x70，
              mail: 'john@example.com', //有权访问编辑者或编辑者的公司或个人的电子邮件地址
              name: '欧阳锋', //该公司或个人的谁可以访问编辑或编辑作者，名称
              www: 'example.com', //以上公司或个人的家庭网站地址，
            },
            feedback: {
              //反馈配置信息
              url: 'https://example.com', //单击“反馈和支持”菜单按钮时将打开的网站地址的绝对URL ，
              visible: false, //显示或隐藏“反馈和支持”菜单按钮，
            },
            goback: {
              //定义“打开文件位置”菜单按钮和右上角按钮的设置。该对象具有以下参数：
              blank: true, //在新的浏览器选项卡/窗口（如果值设置为true）或当前选项卡（如果值设置为false）中打开网站。默认值为true，
              requestClose: false, //定义如果单击“打开文件位置”按钮，则调用events.onRequestClose事件，而不是打开浏览器选项卡或窗口。默认值为false，
              text: 'Open file location', //将在“打开文件位置”菜单按钮和右上角按钮（即，而不是“转到文档”）上显示的文本，
              url: 'https://example.com', //单击“打开文件位置”菜单按钮时将打开的网站地址的绝对URL ，
            },
            logo: {
              image: 'https://example.com/logo.png', //图像文件的路径，用于在普通工作模式下显示（即，在所有编辑器的查看和编辑模式下）。图片必须具有以下尺寸：172x40，
              imageEmbedded: 'https://example.com/logo_em.png', //用于以嵌入式模式显示的图像文件的路径（请参阅config部分以了解如何定义嵌入式文档类型）。图片必须具有以下尺寸：248x40，
              url: 'https://www.baidu.com', //某人单击徽标图像时将使用的绝对URL（可用于转到您的网站等）。保留为空字符串或null以使徽标不可单击，
            },
          },
          user: {
            //用户信息
            id: 'admin', //用户ID
            name: '操作员', //用户全名称
          },
          embedded: {
            //Embedded部分仅适用于嵌入式文档类型（请参阅config部分以了解如何定义嵌入式文档类型）。它允许更改设置，这些设置定义嵌入式模式下按钮的行为。
            embedUrl: 'https://example.com/embedded?doc=exampledocument1.docx', //定义文档的绝对URL，以作为嵌入到网页中的文档的源文件
            fullscreenUrl: 'https://example.com/embedded?doc=exampledocument1.docx#fullscreen', //定义将以全屏模式打开的文档的绝对URL。
            saveUrl: 'https://example.com/download?doc=exampledocument1.docx', //定义允许将文档保存到用户个人计算机上的绝对URL。
            shareUrl: 'https://example.com/view?doc=exampledocument1.docx', //定义允许其他用户共享此文档的绝对URL。
            toolbarDocked: 'top', //定义嵌入式查看器工具栏的位置，可以为top或bottom。
          },
        },

        events: {
          //事件配置
          // onAppReady,//-将应用程序加载到浏览器时调用的函数。
          // onCollaborativeChanges //-当文档由其他用户在严格共同编辑模式下共同编辑时调用的函数。
          // onDocumentReady,//-将应用程序加载到浏览器时调用的函数。
          // onDocumentStateChange,//-修改文档时调用的函数。这就是所谓的使用参数：{真正的“数据”}在当前用户编辑文档以及与参数：{“数据”：假}在当前用户的更改发送到文档编辑服务。
          // onDownloadAs,//-调用downloadAs方法时，使用指向已编辑文件的绝对URL调用的函数。在data参数中发送要下载的文档的绝对URL 。
          // onError,//-发生错误或其他特定事件时调用的函数。错误消息在data参数中发送。==
          // onInfo,//-应用程序打开文件时调用的函数。该模式在data.mode参数中发送。可以查看或编辑。
          // onMetaChange,//-通过meta命令更改文档的元信息时调用的函数。文档名称通过data.title参数发送。
          // onOutdatedVersion,//-使用旧的document.key值打开文档进行编辑时，显示错误后调用的函数，该值用于编辑先前的文档版本并已成功保存。调用此事件时，必须使用新的document.key重新初始化编辑器。
          // onReady,//-将应用程序加载到浏览器时调用的函数。自从5.0版本不推荐使用，请使用onAppReady代替
          // onRequestClose,//-结束编辑器的工作并且必须关闭编辑器时调用的函数。==
          // onRequestCompareFile,//-用户尝试通过单击“存储中的文档”按钮来选择要比较的文档时调用的函数。要选择要比较的文档，必须调用setRevisedFile方法。如果未声明该方法，则不会显示“来自存储的文档”按钮。
          // onRequestCreateNew,//-用户尝试通过单击“新建”按钮来创建文档时调用的函数。使用此方法代替createUrl字段。如果未声明该方法且未指定createUrl，则将不会显示“创建新”按钮。
          // onRequestEditRights,//-用户尝试通过单击“编辑文档”按钮尝试将文档从视图切换到编辑模式时调用的函数。调用该函数时，必须在编辑模式下再次初始化编辑器。如果未声明该方法，则不会显示“编辑”按钮。
          // onRequestHistory,//-用户尝试通过单击“版本历史记录”按钮显示文档版本历史记录时调用的函数。要显示文档版本历史，您必须调用refreshHistory方法。如果未声明该方法和onRequestHistoryData方法，则不会显示“版本历史记录”按钮。
          // onRequestHistoryClose,//-当用户尝试通过单击“关闭历史记录”按钮来查看文档版本历史记录时，试图调用该文档时调用的函数。调用该函数时，必须在编辑模式下再次初始化编辑器。如果未声明该方法，则不会显示“关闭历史记录”按钮。
          // onRequestHistoryData,//-用户尝试单击文档版本历史记录中的特定文档版本时调用的函数。
          // onRequestInsertImage,//-用户尝试通过单击“保存图像”按钮插入图像时调用的函数。图像插入的类型在参数data.c中指定。
          // onRequestRename,//-用户尝试通过单击“重命名...”按钮重命名文件时调用的函数。
          // onRequestRestore,//-用户单击版本历史记录中的“还原”按钮来还原文件版本时调用的函数。
          // onRequestSaveAs,//-用户尝试通过单击“另存为...”按钮保存文件时调用的函数。文档的标题和要下载的文档的绝对URL在data参数中发送。如果未声明该方法，则不会显示“另存为...”按钮。
          // onRequestSharingSettings,//-用户单击“更改访问权限”按钮来管理文档访问权限时调用的函数。必须调用setSharingSettings方法来更新有关允许与其他用户共享文档的设置的信息。如果未声明该方法，则不会显示“更改访问权限”按钮。
          // onRequestUsers,//-评论者可以选择要在评论中提及的其他用户时调用的函数。要设置用户列表，必须调用setUsers方法。
          // onWarning,//-发生警告时调用的函数。警告消息在data参数中发送。
          // "onDocumentStateChange": function() {
          // }, //文档改变后的回调
          //"onDocumentReady" : onDocumentReady, //文档初始化准备好后的回调
        },
      }
      const docEditor = new DocsAPI.DocEditor('preview', config)
    </script>
  </body>
</html>

核心配置项说明

document（文档信息）

字段说明
documentType文档类型：text（文档）/ spreadsheet（表格）/ presentation（演示文稿）
key文档唯一标识，每次编辑保存后必须重新生成，否则会提示版本过期
title文件名，下载文档时也会使用该名称
url存储原始文档的绝对 URL，OnlyOffice 服务会从这里拉取文件
permissions权限配置：edit（可否编辑）、print（可否打印）、download（可否下载）等

editorConfig（编辑配置）

  • mode：view（只读视图）或 edit（编辑模式）
  • callbackUrl：保存文件时的回调地址，用户点保存后 OnlyOffice 服务会把编辑后的文件回传给该地址，由后端接收并落库
  • lang：界面语言，如 zh-CN
  • customization：界面定制（是否显示帮助、聊天、自动保存、徽标 logo 等）
  • user：当前操作者信息（id、name），用于协同编辑时标识用户

events（事件回调）

常用事件：

  • onAppReady：编辑器加载完成
  • onDocumentReady：文档就绪
  • onDocumentStateChange：文档内容被修改（data 为 true 表示有未保存修改）
  • onError：发生错误
  • onRequestSaveAs：用户点击”另存为”
1
2
3
4
// 监听文档修改状态，用于提示用户是否保存
docEditor.events.on('documentStateChange', function (e) {
  console.log(e.data); // true = 有未保存的修改
});

注意：key 在每次保存后必须重新生成，否则再次打开会触发 onOutdatedVersion 错误提示，需用新的 key 重新初始化编辑器。

]]> https://blog.zhangsifan.com/posts/20251011oo/ 2025-10-10T16:00:00.000Z OnlyOffice 前端使用教程：通过 JavaScript API 在网页中集成在线文档编辑器 OnlyOffice 前端使用教程 2025-10-10T16:00:00.000Z JCAlways 问题背景

在 Switch 版本中，任天堂出于安全因素考虑，屏蔽了使用 IP 地址连接自建服务器的功能，对 Switch 端的游玩造成了较大的不便。

解决原理

本文使用了基于小米路由器自定义Hosts的原理，通过将 Switch 版本中的默认联机服务器的 IP 地址劫持为目标服务器，实现了 Switch 版连接自建云服务器的功能。

具体流程：

  1. Switch 启动我的世界联机功能时，会向默认的几个服务器域名（如 hivebedrock.network）发起 DNS 解析请求
  2. 路由器上的自定义 Hosts 拦截这些请求，把域名解析到你自建服务器的 IP
  3. Switch 因此连接到了你的服务器，实现”以假乱真”的联机

前置条件

  • 一台支持自定义 Hosts 的路由器（本文以小米路由器为例，其他路由器如 OpenWrt、梅林固件原理相同）
  • 一台已搭建好的我的世界基岩版服务器（需对外开放端口，本文以局域网 192.168.1.88 为例）

修改路由器 Hosts

进入小米路由器后台 →「高级设置」→「自定义 Hosts」，添加以下内容（将 192.168.1.88 替换为你的服务器 IP）：

1
2
3
4
5
192.168.1.88 hivebedrock.network
192.168.1.88 mco.mineplex.com
192.168.1.88 play.inpvp.net
192.168.1.88 mco.lbsg.net
192.168.1.88 mco.cubecraft.net

各域名对应的服务器

域名说明
hivebedrock.networkHive 基岩服务器
mco.mineplex.comMineplex 基岩服务器
play.inpvp.netInPvP 基岩服务器
mco.lbsg.netLifeboat 基岩服务器
mco.cubecraft.netCubeCraft 基岩服务器

连接步骤

  1. 保存并应用路由器 Hosts 配置
  2. 让 Switch 与路由器处于同一局域网（或路由器为 Switch 提供 DHCP）
  3. 打开 Switch 上的我的世界，进入「游戏」→「服务器」标签
  4. 任选一个默认服务器列表中的服务器点击连接，此时实际连接的将是你的自建服务器
  5. 若连接失败，检查服务器是否已开放端口、IP 是否正确

提示：该方法原理是 DNS 劫持，仅适用于当前局域网；如需远程连接，可考虑自建 DNS 服务或使用 VPN 组网。

]]> https://blog.zhangsifan.com/posts/20250925mc/ 2025-09-24T16:00:00.000Z 通过小米路由器自定义 Hosts 劫持，让 Nintendo Switch 版我的世界连接自建第三方服务器 Nintendo Switch 我的世界 连接第三方服务器 2025-09-24T16:00:00.000Z JCAlways 官方文档

GitLab CE（Community Edition）是开源的代码托管平台，支持 Git 仓库管理、CI/CD、Issue 追踪等功能。本文介绍如何通过宝塔面板的 Docker 功能一键安装 GitLab CE，并配置域名、HTTPS 与邮件服务。

安装

使用 宝塔面板 Docker 安装

在宝塔面板 →「Docker」→「项目编排（Compose）」中创建项目，填写下面的 docker-compose.yml 与 .env 文件，一键启动即可。

gitlab安装配置

完整docker-compose.yml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52

services:
  gitlab:
    image: gitlab/gitlab-ce:${VERSION}
    #    container_name: ${CONTAINER_NAME}
    deploy:
      resources:
        limits:
          cpus: ${CPUS}
          memory: ${MEMORY_LIMIT}
    restart: always
    hostname: ${DOMAIN_HOST}
    shm_size: '256m'
    ports:
      - ${HOST_IP}:${WEB_HTTP_PORT}:80
      - ${HOST_IP}:${WEB_HTTPS_PORT}:443
      - ${HOST_IP}:${WEB_SSH_PORT}:22
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        # Add any other gitlab.rb configuration here, each on its own line
        external_url 'https://${DOMAIN_HOST}'
        nginx['listen_port'] = 80
        nginx['listen_https'] = false
        nginx['proxy_set_headers'] = { "X-Forwarded-Proto" => "https", "X-Forwarded-Ssl" => "on" }
        nginx['client_max_body_size'] = '0'
        nginx['proxy_read_timeout'] = 600
        nginx['proxy_connect_timeout'] = 600
        nginx['proxy_send_timeout'] = 600
        nginx['gzip_enabled'] = false
        gitlab_rails['smtp_enable'] = true
        gitlab_rails['smtp_address'] = "smtp.ym.163.com"
        gitlab_rails['smtp_port'] = 465
        gitlab_rails['smtp_user_name'] = "robot@domain.com"
        gitlab_rails['smtp_password'] = "PASSWORD"
        gitlab_rails['smtp_domain'] = "smtp.ym.163.com"
        gitlab_rails['smtp_authentication'] = "login"
        gitlab_rails['smtp_enable_starttls_auto'] = false
        gitlab_rails['smtp_tls'] = true
        gitlab_rails['gitlab_email_from'] = 'robot@domain.com'
    volumes:
      - ${APP_PATH}/config:/etc/gitlab
      - ${APP_PATH}/logs:/var/log/gitlab
      - ${APP_PATH}/data:/var/opt/gitlab
    labels:
      createdBy: "bt_apps"
    networks:
      - baota_net

networks:
  baota_net:
    external: true

完整.env

1
2
3
4
5
6
7
8
9
10
VERSION=latest
CONTAINER_NAME=CONTAINER_NAME
HOST_IP=127.0.0.1
WEB_HTTP_PORT=10080
WEB_HTTPS_PORT=10443
WEB_SSH_PORT=10022
DOMAIN_HOST=git.domain.com
CPUS=0
MEMORY_LIMIT=0MB
APP_PATH=/www/dk_project/dk_app/gitlab/gitlab

配置说明

  • external_url：GitLab 对外访问地址，配置为你的域名（如 https://git.domain.com），配合反向代理实现 HTTPS
  • GITLAB_OMNIBUS_CONFIG：GitLab 的 omnibus 配置入口，所有 gitlab.rb 的配置项都可以写在这里，如 SMTP 邮件、超时时间、上传大小限制等
  • .env 文件：WEB_HTTP_PORT / WEB_HTTPS_PORT / WEB_SSH_PORT 为宿主机映射端口，APP_PATH 为数据持久化目录，升级或迁移时保留该目录即可
  • 首次登录：浏览器访问 https://git.domain.com，使用管理员账号 root，初始密码存放在容器 /etc/gitlab/initial_root_password 文件中，也可用 docker exec gitlab cat /etc/gitlab/initial_root_password 查看

邮件服务配置

官方文档

在docker-compose.yml 中GITLAB_OMNIBUS_CONFIG 修改

网易免费企业邮箱

1
2
3
4
5
6
7
8
9
10
gitlab_rails['smtp_enable'] = true
gitlab_rails['smtp_address'] = "smtp.ym.163.com"
gitlab_rails['smtp_port'] = 465
gitlab_rails['smtp_user_name'] = "xxxx@xx.com"
gitlab_rails['smtp_password'] = "password"
gitlab_rails['smtp_authentication'] = "login"
gitlab_rails['smtp_enable_starttls_auto'] = false
gitlab_rails['smtp_tls'] = true
gitlab_rails['gitlab_email_from'] = 'xxxx@xx.com'
gitlab_rails['smtp_domain'] = "smtp.ym.163.com"

测试 SMTP 配置

您可以使用 Rails 控制台验证 GitLab 是否能够正常发送电子邮件。在 GitLab 服务器上，执行gitlab-rails console进入控制台。然后，您可以在控制台提示符下输入以下命令，让 GitLab 发送一封测试电子邮件：

1
Notify.test_email('destination_email@address.com', 'Message Subject', 'Message Body').deliver_now
]]> https://blog.zhangsifan.com/posts/20250905gl/ 2025-09-03T16:00:00.000Z 使用宝塔面板 Docker 安装 Gitlab CE 服务器 搭建 Gitlab CE 服务器 2025-09-03T16:00:00.000Z JCAlways RTMP（Real-Time Messaging Protocol）是目前直播推流最常用的协议，OBS、FFmpeg 等工具都支持向 RTMP 服务器推流。本文介绍如何使用开源的 smart_rtmpd 快速搭建一个本地 RTMP 推流服务器，配合 OBS 即可实现多端直播推流。

官方网站

下载服务端软件

下载 rtmpd.zip 文件

rtmpd.zip

smart_rtmpd 是一个跨平台（Windows / Linux / Mac）的 RTMP 流媒体服务器，支持：

  • 直播流推流与转发
  • HLS / HTTP-FLV 拉流
  • 按需转码与录制
  • 简单易用的 Web 管理界面

解压运行

  • 解压 rtmpd.zip 文件
    • 然后解压 smart_rtmpd_win.zip 文件夹
    • 运行 smart_rtmpd.exe 重新
    • 点击 启动 即可

启动后服务默认监听 1935 端口（RTMP 标准端口），Web 管理界面默认端口为 8080（以程序提示为准），通过浏览器访问即可管理推流与拉流地址。

OBS 推流配置

在 OBS 中配置推流地址，即可向本机 RTMP 服务器推流：

  1. 打开 OBS，点击「设置」→「直播」
  2. 服务类型选择自定义
  3. 服务器地址填写：rtmp://127.0.0.1:1935/live
  4. 串流密钥填写一个自定义的名称，如：test（作为流的标识）
  5. 点击「开始推流」

推流完成后，可通过以下地址拉流验证：

  • HTTP-FLV：http://127.0.0.1:8080/live/test.flv
  • HLS：http://127.0.0.1:8080/live/test.m3u8

提示：如需将流推送到公网或其他设备观看，需要把服务器部署到公网主机，并在防火墙开放 1935 与 8080 端口。

]]> https://blog.zhangsifan.com/posts/20250707mp/ 2025-07-06T16:00:00.000Z 使用 smart_rtmpd 搭建 RTMP 推流服务器，配合 OBS 实现本地多端推流直播 搭建 RTMP 推流服务 2025-07-06T16:00:00.000Z JCAlways 官方网站

OBS Studio 下载

Download | OBS

OBS 多流推送插件下载

下载地址

Windows 安装方式

下载插件

下载 obs-multi-rtmp-x.x.x.x-windows-x64.zip 文件

解压安装插件

将 data 中的文件放到 OBS 安装目录的 data 文件夹中
将 obs-plugins 中的文件放到 OBS 安装目录的 obs-plugins 文件夹中

Mac OS 安装方式

下载插件

下载 obs-multi-rtmp-x.x.x.x-macos-universal.pkg 文件

安装插件

双击下载的文件安装即可

使用插件

重新启动 OBS Studio 即可在 停靠窗口 -> 多路推流 使用

示例

]]> https://blog.zhangsifan.com/posts/20250707zb/ 2025-07-06T16:00:00.000Z OBS多站点并发插件 OBS 多流推送 2025-07-06T16:00:00.000Z JCAlways 下载服务器文件
  • 服务器系统 Ubuntu 22+
  • 我们建议在至少具有 2 个内核和 1 Gb RAM 的 64 位 Intel 或 AMD 处理器机器上运行 Bedrock Minecraft 服务器。

点击下载基岩版服务器文件

下载后上传至服务器 并解压文件

宝塔服务器设置

宝塔面板设置页面

服务器防火墙

阿里云服务器防火墙设置

记得 协议类型 选择全部流量!!!

阿里云防火墙设置.png

配置

服务器将尝试读取名为 server.properties 的文件。其中一些选项仅在创建新世界时读取，而另一些选项则在每次启动时读取。该文件应包含一个列表，其中的键和值以等号分隔，每行一个。

有以下选项可用。如果值是括号中的数字，则可以使用该数字代替文本值。

Option namePossible valuesDefault valueWhen is it usedNotes
server-nameAny string (no semicolon allowed)Dedicated ServerAlways这是游戏内服务器列表中显示的服务器名称。list.
gamemodesurvival, creative, adventuresurvivalAlways or only for new players
force-gamemodetrue, falsefalseAlwaysforce-gamemode=false（或 server.properties 文件中未定义 force-gamemode）可防止服务器向客户端发送除服务器在世界创建期间保存的 gamemode 值之外的 gamemodes 值，即使这些值是在世界创建后在 server.propertie 文件中设置的。force gamemode=true强制服务器向客户端发送gamemode值，而不是服务器在世界创建期间保存的gamemode值（如果这些值在世界创建后在server.properties文件中设置）。
difficultypeaceful, easy, normal, hardeasyAlways
allow-cheatstrue, falsefalseAlways如果为true，则可以使用命令等作弊手段。
max-playersAny integer10AlwaysThe maximum numbers of players that should be able to play on the server. Higher values have performance impact.
server-portInteger between 1024 and 6553519132Always可以使用低于1024的值，但通常保留用于众所周知的应用
server-portv6Integer between 1024 and 6553519133Always可以使用低于1024的值，但通常保留用于众所周知的应用
enable-lan-visibilitytrue, falsetrueAlways倾听并回应在局域网上寻找服务器的客户端。这将导致服务器绑定到默认端口（19132、19133），即使“服务器端口”和“server-portv6”具有非默认值。如果不需要LAN发现，或者在同一主机上运行多个服务器可能导致端口冲突，请考虑关闭此功能。
level-nameAny stringBedrock levelAlwaysThe name of level to be used/generated. Each level has its own folder in /worlds.
level-seedAny stringWorld creationThe seed to be used for randomizing the world. If left empty a seed will be chosen at random.
online-modetrue, falsetrueAlwaysIf true, all connected players must be authenticated with Xbox Live. Clients connecting to remote (non-LAN) servers will always require Xbox Live authentication regardless of this setting. If the server accepts connections from the Internet, then it is highly recommended to enable online-mode.
allow-listtrue, falsefalseAlwaysIf true then all connected players must be listed in the separate allowlist.json file. See the Allowlist section.
view-distanceAny integer greater than 532AlwaysThe maximum allowed view distance. Higher values have performance impact.
player-idle-timeoutAny positive integer, including 030AlwaysAfter a player has idled for this many minutes they will be kicked. If set to 0 then players can idle indefinitely.
max-threadsAny integer8AlwaysMaximum number of threads the server will try to use. If set to 0 or removed then it will use as many as possible.
tick-distanceAn integer in the range [4, 12]4AlwaysThe world will be ticked this many chunks away from any player. Higher values have performance impact.
default-player-permission-levelvisitor, member, operatormemberAlwaysWhich permission level new players will have when they join for the first time.
texturepack-requiredtrue, falsefalseAlwaysIf the world uses any specific texture packs then this setting will force the client to use it.
content-log-file-enabledtrue, falsefalseAlwaysEnables logging content errors to a file.
compression-thresholdAn integer in the range [0-65535]1AlwaysDetermines the smallest size of raw network payload to compress. Can be used to experiment with CPU-bandwidth tradeoffs.
compression-algorithmzlib, snappyzlibAlwaysDetermines the compression algorithm to use for networking.
server-authoritative-movement-stricttrue, falsefalseAlwaysIf true, will be more strict toward the Player position and be less permissive in accepting the client info. This will impact Player around moving block if there is high latency.
server-authoritative-dismount-stricttrue, falsefalseAlwaysIf true, will be more strict toward the Player dismount position. This means clients will receive a correction on their dismount position in higher latency situation.
server-authoritative-entity-interactions-stricttrue, falsefalseAlwaysIf true, will be more strict toward the Entity interactions. This will impact Players interacting with each other in higher latency situations.
player-position-acceptance-thresholdAny positive float0.5AlwaysThis is the tolerance of discrepancies between the Client and Server Player position. This helps in problematic scenarios. The higher the number, the more tolerant the server will be before asking for a correction. Passed value of 1.0, the chance of missing cheating increases.
player-movement-action-direction-thresholdAny positive float in the range of [-1.00, 1.00]0.85AlwaysThe amount that the direction the player is attacking can differ from the direction the player is looking as cos(x) where x is the angle between the two vectors. A value of 1 means the two vectors must be parallel, 0 means anything in front of the player, and -1 means any vector.
server-authoritative-block-breakingtrue, falsefalseNot when client-authIf true, the server will compute block mining operations in sync with the client so it can verify that the client should be able to break blocks when it thinks it can. This setting cannot be combined with client authoritative movement and will be disabled if that setting is enabled.
server-authoritative-block-breaking-pick-range-scalarAny float above 1.01.5When server-authoritative-block-breaking is trueThis increase the range of block breaking. This is squared and multiplied with the default range.
chat-restrictionNone, Dropped, DisabledNoneAlwaysThis represents the level of restriction applied to the chat for each player that joins the server. “None” is the default and represents regular free chat. “Dropped” means the chat messages are dropped and never sent to any client. Players receive a message to let them know the feature is disabled. “Disabled” means that unless the player is an operator, the chat UI does not even appear. No information is displayed to the player.
disable-player-interactiontrue, falsefalseAlwaysIf true, the server will inform clients that they should ignore other players when interacting with the world. This is not server authoritative.
client-side-chunk-generation-enabledtrue, falsetrueAlwaysIf true, the server will inform clients that they have the ability to generate visual level chunks outside of player interaction distances.
block-network-ids-are-hashestrue, falsetrueAlwaysIf true, the server will send hashed block network ID’s instead of id’s that start from 0 and go up. These id’s are stable and won’t change regardless of other block changes.
disable-personatrue, falsefalseInternal Use Only
disable-custom-skinstrue, falsefalseAlwaysIf true, disable players customized skins that were customized outside of the Minecraft store assets or in game assets. This is used to disable possibly offensive custom skins players make.
server-build-radius-ratioDisabled, 0.0-1.0DisabledAlwaysIf “Disabled” the server will dynamically calculate how much of the player’s view it will generate, assigning the rest to the client to build. Otherwise from the overridden ratio tell the server how much of the player’s view to generate, disregarding client hardware capability. Only valid if client-side-chunk-generation-enabled is enabled.

文件夹

解压后，您将看到几个文件夹和一个二进制可执行文件。首次启动服务器时，将创建一堆新的（空）文件夹。您需要关注的文件夹如下：

Folder namePurpose
behavior_packs这里可以安装新的行为包。目前还无法在关卡中激活它们。
resource_packs这里可以安装新的资源包。目前无法在关卡中激活它们。
worlds如果此文件夹不存在，则会在启动时创建。每个创建的世界都会有一个根据其文件level-name内容命名的文件夹server.properties。

允许列表

如果allow-list启用了此属性，server.properties则服务器将仅允许选定的用户连接。要允许用户连接，您需要知道他们的 Xbox Live 玩家代号。将用户添加到允许列表的最简单方法是使用命令allowlist add <Gamertag>（例如：）allowlist add ExampleName。注意：如果玩家代号中有空格，则需要用双引号将其括起来：allowlist add "Example Name"

如果您稍后想从列表中删除某人，您可以使用命令allowlist remove <Gamertag>。

允许列表将保存在名为 的文件中allowlist.json。如果您想自动执行从中添加或删除玩家的过程，您可以这样做。修改文件后，您需要运行该命令allowlist reload以确保服务器知道您的新更改。

注意：此文件之前名为whitelist.json。为了向后兼容，如果whitelist.json存在其他文件，则将使用该文件代替allowlist.json。要迁移，请删除默认allowlist.json文件，重命名whitelist.json为allowlist.json，然后重启服务器。

该文件包含一个 JSON 数组，其中的对象包含以下键/值。

KeyTypeValue
nameString用户的玩家代号。
xuidString可选。用户的 XUID。如果未设置，则当名称匹配的用户连接时，系统会填充该值。
ignoresPlayerLimitBoolean如果此用户不应计入最大玩家限制，则为 True。目前，即使玩家使用此选项，连接玩家数量仍存在另一个软限制，即 30 人（或比指定的最大玩家数量多 1 人）。此限制的目的是即使服务器已满，也能让一些玩家加入。

示例 allowlist.json 文件:

1
2
3
4
5
6
7
8
9
10
11
[
    {
        "ignoresPlayerLimit": false,
        "name": "MyPlayer"
    },
    {
        "ignoresPlayerLimit": false,
        "name": "AnotherPlayer",
        "xuid": "274817248"
    }
]

权限

permissions.json您可以通过在与服务器可执行文件位于同一目录中的 中为玩家分配角色来调整玩家的特定权限。该文件包含一个带有 XUID 和权限的简单 JSON 对象。有效权限为： operator、member、visitor每个使用这些帐户连接的玩家都将根据设置的权限进行处理。如果您在服务器运行时更 ​​ 改此文件，请运行该命令permission reload以确保服务器知道您的新更改。您还可以使用 列出当前权限permission list。请注意，online-mode需要启用 才能使此功能正常工作，因为 xuid 需要对用户帐户进行在线验证。如果不在该列表中的新玩家连接，default-player-permission-level 则将应用该选项。

示例permissions.json文件：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
[
    {
        "permission": "operator",
        "xuid": "451298348"
    },
    {
        "permission": "member",
        "xuid": "52819329"
    },
    {
        "permission": "visitor",
        "xuid": "234114123"
    }
]

崩溃报告

如果服务器崩溃，它会自动向我们发送各种信息，帮助我们解决将来的问题。

命令

您可以通过在控制台中输入命令来向服务器发出命令。以下命令可用。< > 表示参数为必需参数，[ ] 表示参数为可选参数，| 表示不同的允许值。如果字符串包含空格，则可以用双引号 “ 括起来。

Command syntaxDescription
kick < player name or xuid > < reason >立即踢出一名玩家。踢出原因将显示在被踢出玩家的屏幕上。
stop正常关闭服务器。

备份

服务器支持在运行时备份世界文件。手动备份不太方便，但自动备份效果更好。从服务器角度来看，备份包含三个命令。

CommandDescription
save hold这将要求服务器准备备份。它是异步的，并将立即返回。
save query调用此命令后，save hold 您应该反复调用该命令，以查看准备工作是否完成。如果返回成功，它将返回一个文件列表（包含每个文件的长度），其中包含您需要复制的文件。服务器在执行此操作时不会暂停，因此某些文件可能会在备份过程中被修改。只要您只复制给定文件列表中的文件，并将复制的文件截断为指定的长度，备份就应该是有效的。
save resume当您完成文件复制后，您应该调用它来告诉服务器可以再次删除旧文件。
]]> https://blog.zhangsifan.com/posts/20250424mc/ 2025-04-23T16:00:00.000Z 使用Ubuntu Linux搭建Minecraft基岩(Bedrock)服务器 零基础搭建Minecraft基岩(Bedrock)服务器 2025-04-23T16:00:00.000Z JCAlways 官方网站

什么是 PageSpy？

PageSpy 是一款兼容 Web / 小程序 / React Native / 鸿蒙 App 等平台项目的开源调试平台。基于对原生 API 的封装，它将调用原生方法时的参数进行过滤、转化，整理成一定格式的消息供调试端消费；调试端收到消息数据后，提供类似本地控制台的功能界面将数据呈现出来。

为什么是 PageSpy?

一图胜千言。

为什么选择 PageSpy 示意图

何时使用？

任何无法在本地使用控制台调试的场景，都是 PageSpy 可以大显身手的时候！ 一起来看下面的几个场景案例：

  • 本地调试 H5、Webview 应用：以往有些产品提供了可以在 H5 上查看信息的面板，但移动端屏幕太小操作不便、显示不友好，以及信息被截断等问题；
  • 远程办公、跨地区协同：传统沟通方式如邮件、电话、视频会议等，沟通效率不高、故障信息不全面，容易误解误判；
  • 用户终端上出现白屏问题：传统定位问题的方式包括数据监控、日志分析等，这些方式依赖排障人员要理解业务需求场景、技术实现；

PageSpy 的目标，就是为包括以上场景的人员提供帮助。

服务部署

使用 Docker 部署

1
docker run -d --restart=always -v ./log:/app/log -v ./data:/app/data -p 6752:6752 --name="pageSpy" ghcr.io/huolalatech/page-spy-web:latest

执行完成后，打开浏览器访问 http://localhost:6752 即可访问服务。

视频学习

客户端部署

浏览器

导入 SDK

1
2
3
4
5
6
<!-- PageSpy SDK -->
<script crossorigin="anonymous" src="https://<your-pagespy-host>/page-spy/index.min.js"></script>

<!-- 插件（非必须，但建议使用） -->
<script crossorigin="anonymous" src="https://<your-pagespy-host>/plugin/data-harbor/index.min.js"></script>
<script crossorigin="anonymous" src="https://<your-pagespy-host>/plugin/rrweb/index.min.js"></script>

初始化 PageSpy 和插件

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
window.$harbor = new DataHarborPlugin();
window.$rrweb = new RRWebPlugin();

[window.$harbor, window.$rrweb].forEach((p) => {
  PageSpy.registerPlugin(p);
});

window.$pageSpy = new PageSpy({
  // 配置项
  api?: string;
  clientOrigin?: string;

  // "project" is an aggregation of information that can be searched in the room list on the debug side.
  // default: 'default'
  project?: string;

  // "title" is a user-defined parameter that can be used to distinguish the current debugging client,
  // and the corresponding information is displayed under the "device id" in each debugging connection panel.
  // default: '--'
  title?: string;

  // Indicates whether the SDK will automatically render the "Circle with Logo on White Background"
  // control in the bottom left corner of the client when initiation is complete. If set to false,
  // you can call window.$pageSpy.render() to render it manually.
  // default: true
  autoRender?: boolean;

  // Manually specify the scheme of the PageSpy service.
  // This works if the SDK can't correctly analyse the scheme, e.g. if PageSpy's browser plugin
  // is introduced into the SDK via chrome-extension://xxx/sdk/index.min.js, which will be
  // be parsed by the SDK as an invalid "chrome-extension://" and fallback to ["http://", "ws://"].
  //   - (Default) Pass the value undefined or null: the SDK will parse it automatically;
  //   - Pass boolean value:
  //     - true: the SDK will access the PageSpy service via ["https://", "wss://"].
  //     - false: the SDK will access the PageSpy service via ["http://", "wss://"]
  enableSSL?: boolean | null;

  // All internal plugins are carried with PageSpy by default out of the box.
  // You can disable some plugins as needed.
  disabledPlugins?: (InternalPlugins | string)[];

  // After adding support for offline replay in PageSpy@1.7.4, the client-integrated SDK can work without
  // establishing a connection with the debugger.
  // Default value is false, when users set it to other values will enters "offline mode", where PageSpy
  // will not create rooms or establish WebSocket connections.
  offline?: boolean;

  // Customize logo source url.
  logo?: string;

});

小程序

导入 SDK

在项目中安装依赖。我们提供了几种小程序平台的 SDK，请根据需要安装：

  • 微信小程序
1
yarn add @huolala-tech/page-spy-wechat@latest
  • 支付宝小程序
1
yarn add @huolala-tech/page-spy-alipay@latest
  • UniAPP
1
yarn add @huolala-tech/page-spy-uniapp@latest
  • Taro
1
yarn add @huolala-tech/page-spy-taro@latest

配置白名单

将 PageSpy 服务域名填入小程序的 http、websocket 请求白名单中。注意除了开发环境，小程序强制要求使用 https 和 wss 协议：

1
2
https://<your-pagespy-host>
wss://<your-pagespy-host>

初始化 PageSpy 和插件

在入口文件中引入 SDK 并实例化，初始化参数提供了可选的 配置项 用于自定义 SDK 的行为：

1
2
3
4
5
import PageSpy from "@huolala-tech/page-spy-wechat";

const $pageSpy = new PageSpy({
  api: "<your-pagespy-host>",
});

鸿蒙 App

导入 SDK

在待调试 HAP 目录下安装依赖：

1
2
3
4
5
# API 9
ohpm install @huolala/page-spy-harmony@^1.0.0

# API 11
ohpm install @huolala/page-spy-harmony@^2

初始化 PageSpy 和插件

在合适的位置引入 SDK 并初始化，这里以 EntryAbility 为例。初始化参数提供了可选的 配置项 用于自定义 SDK 的行为：

1
2
3
4
5
6
7
8
9
10
11
12
13
import { PageSpy } from "@huolala/page-spy-harmony";
import axiosInstance from "path/to/your/axios-instance";

export default class EntryAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage) {
    new PageSpy({
      context: this.context,
      api: "<your-pagespy-host>",
      enableSSL: true,
      axios: axiosInstance,
    });
  }
}

常用 API

更新初始化参数

PageSpy 提供了 Device ID 用于识别设备，同时还提供了 project / title 供开发者在初始化时自定义信息，用于辅助识别客户端。但你可能希望在初始化之后更新这些参数信息，操作方式如下：

1
2
// 调用 updateRoomInfo 可以更新 project / title
window.$pageSpy.updateRoomInfo({ project: "xxx", title: "xxx" });

显示隐藏按钮

1
2
3
4
window.$pageSpy = new PageSpy({
  // ... 其他配置参数
  autoRender: false,
});

手动渲染「圆形白底带 Logo」的控件

当 config.autoRender 为 false 时，需要手动调用 render() 方法渲染控件。

1
window.$pageSpy.render();

销毁

PageSpy 会断开连接、从文档中移除相关 DOM、清空已缓存的数据、调用所有已注册插件的 onReset() 方法。
当前上下文中被代理或者被重写的 API，如浏览器中的 window.fetch，都会恢复到实例化 PageSpy 之前的状态。

1
window.$pageSpy.abort();

常见问题

调试端如何加一些安全认证的保护，开发者通过认证才可以访问？

从 2.3.0 版本开始，PageSpy 支持在启动服务时使用变量设置密码以保护调试端安全。设置密码后，开发者访问调试面板时必须输入正确的密码。

允许输入的变量和含义：

  • AUTH_PASSWORD：设置密码；
  • JWT_SECRET：设置 token 的密钥；
  • JWT_EXPIRATION_HOURS：设置 token 过期时间（小时），默认 24 小时；

在启动服务时设置，具体的使用方式如下：

1
docker run -d --restart=always -v ./log:/app/log -v ./data:/app/data -p 6752:6752 --name="pageSpy" -e AUTH_PASSWORD=<password> -e JWT_SECRET=<secret> -e JWT_EXPIRATION_HOURS=<hours> ghcr.io/huolalatech/page-spy-web:latest

2.3.0 之前的版本如何设置密码？

配置
1
2
auth_basic "请输入用户名和密码以访问 PageSpy 服务";
auth_basic_user_file /etc/nginx/.htpasswd;

预览页面 CORS

1
2
3
4
5
6
7
8
9
10
11
server
{
  # 设置CORS
  # 指定响应资源是否允许与给定的 origin 共享
  add_header Access-Control-Allow-Origin '*';
  add_header Access-Control-Allow-Credentials 'true';
  # 配置允许跨域的请求方法
  add_header Access-Control-Allow-Methods 'GET,POST,PUT,DELETE,Options';
  # 配置允许跨域的请求头
  # add_header Access-Control-Allow-Headers 'Authorization,Content-Type,Accept,Origin,User-Agent,Cache-Control,X-Mx-ReqToken,X-Requested-With';
}

更改按钮大小和图片大小

1
2
3
4
5
6
7
8
#__pageSpy .page-spy-logo {
  width: 50px;
  height: 50px;
}
#__pageSpy .page-spy-logo img {
  width: 30px;
  height: 30px;
}

主题(个性化)设置

1
2
3
4
5
6
7
8
9
new PageSpy({
  ...,
  primaryColor: "<主题色>",
  logo: "<悬浮球上的 logo>",
  modal: {
    title: "<弹窗上的标题>",
    logo: "<弹窗上的 logo>",
  },
})
]]> https://blog.zhangsifan.com/posts/20241017dv/ 2024-10-16T16:00:00.000Z 像使用谷歌浏览器的控制台一样简单地开始远程调试。 PageSpy使用教程 2024-10-16T16:00:00.000Z JCAlways 风灵月影（FLiNG）是目前国内使用最广泛的游戏修改器（Trainer）作者之一，其制作的修改器支持大量单机游戏，提供无限生命、无限金币、一击必杀等常用修改功能，适用于单人游戏场景。

官方网站

使用说明

  1. 下载对应游戏的修改器文件
  2. 先启动游戏，进入游戏主界面后，再打开修改器
  3. 按修改器界面提示的快捷键启用对应功能（如 F1 无限生命）
  4. 使用前建议关闭杀毒软件或添加信任，防止误报

注意：修改器仅适用于单机模式，请勿在联机对战中使用，以免影响其他玩家体验。

下载列表

黑神话悟空 - Black Myth: Wukong Trainer

Black.Myth.Wukong.v1.0-v1.0.9.Plus.44.Trainer-FLiNG

荒野大镖客 2 - Red Dead Redemption 2

Red.Dead.Redemption.2.v1.0-v1491.50.Plus.12.Trainer-FLiNG

侠盗猎车手 5 - Grand Theft Auto V

Grand.Theft.Auto.V.v1.0-v1.69.Plus.19.Trainer-FLiNG

赛博朋克 2077 - Cyberpunk 2077

Cyberpunk.2077.v2.0-v2.13.Plus.46.Trainer-FLiNG

注意事项

  • 修改器版本需与游戏版本对应，游戏更新后旧版修改器可能失效，请到官网下载最新版
  • 如杀毒软件拦截，请将修改器文件加入信任列表后重新下载
  • 修改器为 .exe / .rar 压缩包，下载后解压或直接运行即可
]]> https://blog.zhangsifan.com/posts/20240924wg/ 2024-09-23T16:00:00.000Z 风灵月影（FLiNG）游戏修改器下载汇总：黑神话悟空、荒野大镖客2、GTA5、赛博朋克2077 风灵月影下载 2024-09-23T16:00:00.000Z JCAlways 官方网站

基于得分 (v3)

示例

正在自动验证中...

以编程方式调用验证方式

如果您希望更好地控制 reCAPTCHA 的运行时间，可以在 grecaptcha 对象中使用 execute 方法。为此，您需要在 reCAPTCHA 脚本加载中添加 render 参数。

  • 使用您的网站密钥加载 JavaScript API。

    1
    2
    3
    <script src="https://www.google.com/recaptcha/api.js?render=reCAPTCHA_site_key"></script>
    // 如无法连接 Google 服务器，请使用以下地址。
    <script src="https://recaptcha.net/recaptcha/api.js?render=reCAPTCHA_site_key"></script>

  • 针对您要保护的每项操作调用 grecaptcha.execute。

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    function onClick(e) {
      e.preventDefault();
      grecaptcha.ready(function () {
        grecaptcha
          .execute("reCAPTCHA_site_key", { action: "submit" })
          .then(function (token) {
            // Add your logic to submit to your backend server here.
          });
      });
    }

  • 在您的后端验证 reCAPTCHA 令牌。

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    const {
    "success": true|false,      // whether this request was a valid reCAPTCHA token for your site
    "score": number             // the score for this request (0.0 - 1.0)
    "action": string            // the action name for this request (important to verify)
    "challenge_ts": timestamp,  // timestamp of the challenge load (ISO format yyyy-MM-dd'T'HH:mm:ssZZ)
    "hostname": string,         // the hostname of the site where the reCAPTCHA was solved
    "error-codes": [...]        // optional
    } = await fetch("https://www.google.com/recaptcha/api/siteverify", {
      method: "POST",
      headers: {
        "Content-Type": "application/x-www-form-urlencoded; charset=utf-8",
      },
      body: `secret=your_secret&response=${token}`,
    })

基于验证方式 (v2)

示例

代码

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
<html>
  <head>
    <title>reCAPTCHA</title>
    <script
      src="https://www.recaptcha.net/recaptcha/api.js"
      async
      defer
    ></script>
  </head>
  <body>
    <div id="html_element"></div>
    <script>
      function open() {
        grecaptcha.render("html_element", {
          sitekey: "reCAPTCHA_site_key",
          callback: async function (response) {
            await fetch("https://api.zhangsifan.com/google/getReCAPTCHA", {
              method: "POST",
              body: JSON.stringify({
                token: response,
                id: "reCAPTCHA_site_key",
              }),
              headers: {
                "Content-Type": "application/json",
              },
            }).then(async (response) => {
              const { result } = await response.json();
              if (result.success) {
                if (window.confirm("验证成功,是否重置验证器?")) {
                  grecaptcha.reset();
                }
              } else {
                window.alert("验证失败,是否重置验证器?");
                grecaptcha.reset();
              }
            });
          },
        });
      }
      setTimeout(() => open(), 3000);
    </script>
  </body>
</html>
]]> https://blog.zhangsifan.com/posts/20240417re/ 2024-04-16T16:00:00.000Z reCAPTCHA使用先进的风险分析引擎和自适应挑战来防止恶意软件在您的网站上进行滥用活动。与此同时，合法用户将能够登录、购买、查看页面或创建帐户，而虚假用户将被屏蔽。 Google reCAPTCHA使用教程 2024-04-16T16:00:00.000Z JCAlways 使用文档

网站通过使用通行密钥代替密码，可提高用户帐号的安全性并简化用户帐号的管理和使用。借助通行密钥，用户可以使用设备的屏幕锁定功能（例如指纹锁、人脸识别锁或设备 PIN 码）来登录网站或应用。必须先创建通行密钥、将其与用户帐号关联，并将其公钥存储在服务器上，之后用户才能使用该通行密钥进行登录。

示例

示例网站

代码实现

前端代码

安装依赖库

1
npm install @simplewebauthn/browser

后端需实现的接口

Passkey 的完整流程需要前后端配合，核心是以下 4 个接口：

注册验证器

1
2
3
从依赖方（您的服务器）获取注册选项 (/passkey/generate-registration-options)
将身份验证者的回复提交给依赖方进行验证 (/passkey/verify-registration)

使用验证器

1
2
从依赖方（您的服务器）获取身份验证选项 (/passkey/generate-authentication-options)
将身份验证者的回复提交给依赖方进行验证 (/passkey/verify-authentication)

前端流程说明

  • 注册：startRegistration(result) 调用浏览器原生 WebAuthn API，弹出系统级指纹/人脸/PIN 验证；成功后把 attResp（包含公钥凭证）发给后端验证并保存
  • 登录：startAuthentication(result) 同样调用 WebAuthn 完成设备验证，后端校验签名后返回 token，前端拿到后即可视为登录成功
  • 出现 InvalidStateError 表示该设备上的凭据已注册过，需提示用户

示例代码

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
<template>
  <div class="container">
    <el-input
      v-model.trim="state.uniid"
      style="width: 300px"
      placeholder="请输入用户唯一标识符/邮箱账号"
    />
    <el-button @click="init" :disabled="!state.uniid">创建通行密钥</el-button>
    <el-button @click="login">通过通行密钥登录</el-button>
  </div>
</template>
<script setup lang="ts">
import {
  reactive,
  onMounted,
  getCurrentInstance,
  type ComponentInternalInstance,
} from "vue";
import {
  startRegistration,
  startAuthentication,
} from "@simplewebauthn/browser";
import { ElMessage } from "element-plus";
const currentInstance = getCurrentInstance() as ComponentInternalInstance;
const { $UtilsHttp } = currentInstance.appContext.config.globalProperties;
const state = reactive({
  uniid: "",
});
const init = async () => {
  try {
    const { result } = await $UtilsHttp(
      "/passkey/generate-registration-options",
      "get",
      {
        uniid: state.uniid,
      }
    );
    const challenge = result.challenge;
    let attResp;
    try {
      attResp = await startRegistration(result);
    } catch (error) {
      if (error.name === "InvalidStateError") {
        ElMessage.error(
          "Authenticator was probably already registered by user"
        );
      } else {
        ElMessage.error(error.toString());
      }
      throw error;
    }
    try {
      const { result } = await $UtilsHttp(
        "/passkey/verify-registration",
        "post",
        {
          attResp,
          challenge,
        }
      );
      if (result) ElMessage.success("已成功添加通行密钥(PassKey)!");
    } catch (error) {
      ElMessage.error(error.response.data.error);
    }
  } catch (error) {
    ElMessage.error(error.response.data.message);
  }
};
const login = async () => {
  const { result } = await $UtilsHttp(
    "/passkey/generate-authentication-options",
    "get"
  );
  const challenge = result.challenge;
  let asseResp;
  try {
    asseResp = await startAuthentication(result);
  } catch (error) {
    ElMessage.error(error.toString());
    throw error;
  }
  try {
    const {
      result: { flag, token },
    } = await $UtilsHttp("/passkey/verify-authentication", "post", {
      asseResp,
      challenge,
    });
    if (flag) ElMessage.success("使用通行密钥(PassKey)登录成功!!");
  } catch (error) {
    ElMessage.error(error.response.data.message);
  }
};
onMounted(() => {});
</script>
<style lang="less" scoped></style>

后端代码

安装依赖库

1
npm install @simplewebauthn/server
]]> https://blog.zhangsifan.com/posts/20230806pa/ 2023-08-05T16:00:00.000Z 在 Web 应用中使用表单自动填充功能实现通行密钥 通行密钥开发 Passkey 2023-08-05T16:00:00.000Z JCAlways 官方网站

Tauri 是什么？

Tauri 是一个构建适用于所有主流桌面和移动平台的轻快二进制文件的框架。开发者们可以集成任何用于创建用户界面的可以被编译成 HTML、JavaScript 和 CSS 的前端框架，同时可以在必要时使用 Rust、Swift 和 Kotlin 等语言编写后端逻辑。

前置要求

系统依赖项

Windows

Tauri 使用 Microsoft C++ 构建工具进行开发以及 Microsoft Edge WebView2。这些都是在 Windows 上进行开发所必需的。

按照以下步骤安装所需的依赖项。

Microsoft C++ 构建工具

  • 下载 Microsoft C++ 构建工具 安装程序并打开它以开始安装。
  • 在安装过程中，选中“使用 C++ 进行桌面开发”选项。

Visual Studio C++ 构建工具 安装程序 截图

WebView2

WebView 2 已安装在 Windows 10（从版本 1803 开始）和更高版本的 Windows 上。如果你正在这些版本之一上进行开发，则可以跳过此步骤并直接转到 下载并安装 Rust。

Tauri 使用 Microsoft Edge WebView2 在 Windows 上呈现内容。

通过访问 WebView2 Runtime 下载区 安装 WebView2。下载“常青版独立安装程序（Evergreen Boostrapper）”并安装它。

MacOS

Tauri 使用 Xcode 以及各种 macOS 和 iOS 开发依赖项。

从以下位置之一下载并安装 Xcode：

请务必在安装后启动 Xcode，以使它完成设置。

下载并安装 Rust

Tauri 使用 Rust 构建并需要它进行开发。使用以下方法之一安装 Rust。你可以在 https://www.rust-lang.org/tools/install 查看更多安装方法。

Linux/MacOs

1
curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf | sh

Windows

前往 https://www.rust-lang.org/tools/install 下载 rustup。

或者，你可以在 PowerShell 中使用 winget 安装 rustup：

1
winget install --id Rustlang.Rustup

创建项目

使用 create-tauri-app

1
npm create tauri-app@latest

我们建议从基础模板开始（使用 HTML、CSS 和 JavaScript，不使用前端框架），以便快速入门。随后您可以随时引入前端框架。

  • 选择您的前端语言：TypeScript / JavaScript
  • 选择您的包管理器：pnpm
  • 选择您的 UI 模板：Vanilla
  • 选择您的 UI 风格：TypeScript

在 create-tauri-app 创建完项目后，您可以进入项目文件夹，安装依赖，然后使用 Tauri CLI 启动开发服务器：

1
2
3
cd tauri-app
npm install
npm run tauri dev

常用功能

System Tray (系统托盘)

Tauri 允许您为您的应用程序创建和自定义系统托盘。这可以通过提供对常见操作的快速访问来增强用户体验。

配置

首先，更新您的Cargo.toml，以包括系统托盘的必要功能。

1
2
3
# src-tauri/Cargo.toml

tauri = { version = "2.0.0", features = [ "tray-icon" ] }

JavsScript 用法

创建托盘图标

使用 TrayIconTrayIcon.new静态功能创建新的托盘图标：

1
2
3
4
5
6
7
import { TrayIcon } from "@tauri-apps/api/tray";

const options = {
  // here you can add a tray menu, title, tooltip, event handler, etc
};

const tray = await TrayIcon.new(options);

有关自定义选项的更多信息，请参阅TrayIconOptions。

更改托盘图标

创建托盘时，您可以使用应用程序图标作为托盘图标：

1
2
3
4
5
6
7
import { TrayIcon } from "@tauri-apps/api/tray";

const options = {
  icon: "icons/32x32.png",
};

const tray = await TrayIcon.new(options);

添加菜单和事件

要附加在点击托盘时显示的菜单，您可以使用 menu 选项。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
import { TrayIcon } from '@tauri-apps/api/tray';
import { Menu } from '@tauri-apps/api/menu';
import { getCurrentWindow } from "@tauri-apps/api/window"; // 获取当前窗口
import { exit } from "@tauri-apps/plugin-process"; // 进程管理

const menu = await Menu.new({
    [
      {
        id: "show",
        text: "显示窗口",
        action: () => {
          winShowFocus();
        },
      },
      {
        id: "quit",
        text: "退出",
        action: () => {
          exit(0);
        },
      },
    ],
});

const options = {
  menu,
  menuOnLeftClick: false,
};

async function winShowFocus() {
  const win = getCurrentWindow();
  if (!(await win.isVisible())) {
    win.show();
  } else {
    if (await win.isMinimized()) {
      await win.unminimize();
    }
    await win.setFocus();
  }
}

const tray = await TrayIcon.new(options);
显示窗口

tauri 遵循最小权限原则，在运行中可能会碰到如下权限不足的问题：

在 src-tauri/capabilities/default.json 文件的 permissions 属性数组中加入这几个权限：

1
2
3
4
5
6
7
8
9
10
{
  "permissions": [
    "core:window:allow-set-focus",
    "core:window:allow-close",
    "core:window:allow-show",
    "core:window:allow-is-visible",
    "core:window:allow-unminimize",
    "core:window:allow-is-minimized"
  ]
}
退出/重启应用
1
npm run tauri add process

引入 API

1
2
3
4
5
6
import { exit, relaunch } from ‘@tauri-apps/plugin-process’;

// 退出应用
await exit(0);
// 重启应用
await relaunch();
]]> https://blog.zhangsifan.com/posts/20230505tr/ 2023-05-04T16:00:00.000Z 创建小型、快速、安全、跨平台的应用程序 Tauri 2 使用教程 2023-05-04T16:00:00.000Z JCAlways 官方网站

示例

CodePen 示例

前端

准备工作：确保已经在极验用户后台获取到了 captchaId

配置参数

1.引入初始化函数

1
<script src="https://static.geetest.com/static/js/gt.0.4.9.js"></script>

2.初始化

1
<div id="captcha"></div>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
ajax({
  url: "API1接口（详见服务端部署）",
  type: "get",
  dataType: "json",
  success: function (data) {
    //请检测data的数据结构， 保证data.gt, data.challenge, data.success有值
    initGeetest(
      {
        // 以下配置参数来自服务端 SDK
        gt: data.gt,
        challenge: data.challenge,
        offline: !data.success,
        new_captcha: true,
      },
      function (captchaObj) {
        captchaObj.appendTo("#captcha");
      }
    );
  },
});

3.二次验证

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
initGeetest(
  {
    // 省略配置参数
  },
  function (captchaObj) {
    // 省略其他方法的调用
    captchaObj.onSuccess(function () {
      var result = captchaObj.getValidate();
      // ajax 伪代码
      $.ajax({
        url: "服务端",
        data: result,
        dataType: "json",
        success: function (res) {
          console.log(res.result);
        },
      });
    });
  }
);

重置

1
captchaObj.reset();

后端

后端使用 Nodejs + Express

官方 Demo

]]> https://blog.zhangsifan.com/posts/20230330gt/ 2023-03-29T16:00:00.000Z GeeTest3.0使用教程。极验「行为验证」是一项可以帮助你的网站与APP识别与拦截机器程序批量自动化操作的SaaS应用。它是由极验开发的新一代人机验证产品，它不基于传统“问题-答案”的检测模式，而是通过利用深度学习对验证过程中产生的行为数据进行高维分析，发现人机行为模式与行为特征的差异，更加精准地区分人机行为。 GeeTest3.0使用教程 2023-03-29T16:00:00.000Z JCAlways 官方网站

示例

CodePen 示例

前端

准备工作：确保已经在极验用户后台获取到了 captchaId

配置参数

1.引入初始化函数

1
<script src="https://static.geetest.com/v4/gt4.js"></script>

2.初始化

1
<div id="captcha"></div>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
initGeetest4(
  {
    captchaId: "您的captchaId",
    nativeButton: {
      width: "300px",
      height: "40px",
    }, // 极验按钮样式设置
    userInfo: "user@geetest.com", // 用户信息
  },
  function (captcha) {
    // captcha为验证码实例
    captcha.appendTo("#captcha"); // 调用appendTo将验证码插入到页的某一个元素中，这个元素用户可以自定义
  }
);

3.二次验证

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
initGeetest4(
  {
    // 省略配置参数
  },
  function (captchaObj) {
    // 省略其他方法的调用

    // 这里调用了 onSuccess 方法，该方法介绍见下文
    captchaObj.onSuccess(function () {
      var result = captchaObj.getValidate();

      // ajax 伪代码
      $.ajax({
        url: "服务端",
        data: result,
        dataType: "json",
        success: function (res) {
          console.log(res.result);
        },
      });
    });
  }
);

重置

1
captchaObj.reset();

后端

后端使用 Nodejs + Express

官方 Demo

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
var express = require("express");
var querystring = require("querystring");
const crypto = require("crypto");
var axios = require("axios");
var router = express.Router();

// geetest 公钥
// geetest public key
const CAPTCHA_ID = "";

// geetest 密钥
// geetest secret key
const CAPTCHA_KEY = "";

// geetest 服务地址
// geetest server url
const API_SERVER = "http://gcaptcha4.geetest.com";

// geetest 验证接口
// geetest server interface
const API_URL = API_SERVER + "/validate" + "?captcha_id=" + CAPTCHA_ID;

/* GET home page. */
router.get("/", function (req, res, next) {
  res.render("index");
});

router.get("/login", function (req, res, next) {
  req.query = querystring.parse(req.url.split("?")[1]);
  // 前端参数
  // web parameter
  var lot_number = req.query["lot_number"];
  var captcha_output = req.query["captcha_output"];
  var pass_token = req.query["pass_token"];
  var gen_time = req.query["gen_time"];

  // 生成签名, 使用标准的hmac算法，使用用户当前完成验证的流水号lot_number作为原始消息message，使用客户验证私钥作为key
  // 采用sha256散列算法将message和key进行单向散列生成最终的 “sign_token” 签名
  // use lot_number + CAPTCHA_KEY, generate the signature
  var sign_token = hmac_sha256_encode(lot_number, CAPTCHA_KEY);

  // 向极验转发前端数据 + “sign_token” 签名
  // send web parameter and “sign_token” to geetest server
  var datas = {
    lot_number: lot_number,
    captcha_output: captcha_output,
    pass_token: pass_token,
    gen_time: gen_time,
    sign_token: sign_token,
  };

  // post request
  // 根据极验返回的用户验证状态, 网站主进行自己的业务逻辑
  // According to the user authentication status returned by the geetest, the website owner carries out his own business logic
  post_form(datas, API_URL)
    .then((result) => {
      if (result["result"] == "success") {
        console.log("validate success");
        res.send("success");
      } else {
        console.log("validate fail:" + result["reason"]);
        res.send("fail");
      }
    })
    .catch((err) => {
      // 当请求Geetest服务接口出现异常，应放行通过，以免阻塞正常业务。
      // When the request geetest service interface is abnormal, it shall be released to avoid blocking normal business.
      console.log("Geetest server error:" + err);
      res.send("success");
    });
});

// 生成签名
// Generate signature
function hmac_sha256_encode(value, key) {
  var hash = crypto
    .createHmac("sha256", key)
    .update(value, "utf8")
    .digest("hex");
  return hash;
}

// 发送post请求, 响应json数据如：{"result": "success", "reason": "", "captcha_args": {}}
// Send a post request and respond to JSON data, such as: {result ":" success "," reason ":" "," captcha_args ": {}}
async function post_form(datas, url) {
  var options = {
    url: url,
    method: "POST",
    params: datas,
    timeout: 5000,
  };

  var result = await axios(options);

  if (result.status != 200) {
    // geetest服务响应异常
    // geetest service response exception
    console.log("Geetest Response Error, StatusCode:" + result.status);
    throw new Error("Geetest Response Error");
  }
  return result.data;
}

module.exports = router;
]]> https://blog.zhangsifan.com/posts/20230329gt/ 2023-03-28T16:00:00.000Z GeeTest4.0使用教程。行为验证4.0产品是极验于2022年6月正式推出的最新一代验证码产品，结合环境检测、行为特征、POW工作量证明、视觉模型热更等多项技术，在注册、登录、下单、防作弊等多种场景提供人机智能分流验证服务，为企业安全保驾护航。 GeeTest4.0使用教程 2023-03-28T16:00:00.000Z JCAlways 官方文档
KK 开源社区

Docker 容器环境运行

1
2
3
4
5
# 拉取镜像
docker pull keking/kkfileview
# 运行
docker run -it -p 8012:8012 keking/kkfileview
# 浏览器访问容器8012端口 http://172.0.0.1:8012 即可看到项目演示用首页

源码运行

1. 下载源码

1
2
3
4
# gitee
https://gitee.com/kekingcn/file-online-preview.git
# github
https://github.com/kekingcn/kkFileView.git

2. 运行

1
2
3
4
# 进入 kkFileView 目录
cd file-online-preview/server/src/main/java/cn.keking/serverMain
# 运行
main

3. 制作Docker镜像

1
2
3
4
5
6
7
8
9
cd docker/kkfileview-base
docker build --tag keking/kkfileview-base:5.0.0 .

cd ../..
docker build --tag keking/kkfileview:5.0.0 .

docker run -d -p 8012:8012 --name kkfileview keking/kkfileview:5.0.0

docker save -o kkfileview-5.0.0.tar keking/kkfileview:5.0.0

配置文件

file-online-preview/server/src/main/config/application.properties

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
###############################################################################
# 一、服务器基础配置（需要重启生效）
###############################################################################

# 服务器端口号，默认8012
# 可以通过环境变量 KK_SERVER_PORT 覆盖
server.port = ${KK_SERVER_PORT:8012}

# 应用上下文路径，默认为根路径 /
# 可以通过环境变量 KK_CONTEXT_PATH 覆盖
server.servlet.context-path = ${KK_CONTEXT_PATH:/}

# 字符编码设置，统一使用UTF-8
server.servlet.encoding.charset = utf-8

# 启用响应压缩，减少网络传输
server.compression.enabled = true
server.compression.min-response-size = 2048
server.compression.mime-types = application/javascript,text/css,application/json,application/xml,text/html,text/xml,text/plain,font/woff,application/font-woff,font/eot,image/svg+xml,image/x-icon

# 文件上传大小限制，默认500MB
# 注意：需要同时设置spring.servlet.multipart.max-file-size和max-request-size
spring.servlet.multipart.max-file-size = 500MB
spring.servlet.multipart.max-request-size = 500MB

# FreeMarker模板引擎配置
spring.freemarker.template-loader-path = classpath:/web/
spring.freemarker.cache = false
spring.freemarker.charset = UTF-8
spring.freemarker.check-template-location = true
spring.freemarker.content-type = text/html
spring.freemarker.expose-request-attributes = true
spring.freemarker.expose-session-attributes = true
spring.freemarker.request-context-attribute = request
spring.freemarker.suffix = .ftl

# Spring Boot Actuator监控端点配置
management.endpoints.web.exposure.include = health,info,metrics
management.endpoint.health.show-details = always
management.health.defaults.enabled = true


###############################################################################
# 二、Office文档处理配置（部分支持动态配置）
###############################################################################

# Office组件安装路径，默认为自动查找
# Windows示例（注意双反斜杠）：C:\\Program Files (x86)\\OpenOffice 4
# Linux示例：/opt/libreoffice
# MacOS示例：/Applications/LibreOffice.app/Contents
office.home = ${KK_OFFICE_HOME:default}

# Office组件服务端口，支持多个端口实现负载均衡
office.plugin.server.ports = 2001,2002

# Office组件任务超时时间，默认5分钟
office.plugin.task.timeout = 5m

# 每个进程最大任务数，防止内存溢出
office.plugin.task.maxtasksperprocess = 200

# 任务执行超时时间，默认5分钟
office.plugin.task.taskexecutiontimeout = 5m

# Office文档分页范围，支持动态配置
# 默认false，开启后可以指定转换的页面范围
office.pagerange = ${KK_OFFICE_PAGERANGE:false}

# Office文档水印功能，支持动态配置
# 默认false，开启后会在Office文档上添加水印
office.watermark = ${KK_OFFICE_WATERMARK:false}

# Office图片质量，1-100，默认80
# 值越高图片质量越好，但文件越大
office.quality = ${KK_OFFICE_QUALITY:80}

# Office图片最大分辨率，默认150
# 控制生成图片的最大分辨率
office.maximageresolution = ${KK_OFFICE_MAXIMAGERESOLUTION:150}

# 导出Office书签，支持动态配置
# 默认true，转换PDF时保留书签
office.exportbookmarks = ${KK_OFFICE_EXPORTBOOKMARKS:true}

# 是否将Office文档中的批注作为PDF注释导出，默认为true（导出）
# 保留批注便于文档审阅
office.exportnotes = ${KK_OFFICE_EXPORTNOTES:true}

# 加密文档生成的PDF是否添加密码，默认为true（添加）
# 密码为原始加密文档的密码，增强文档安全性
office.documentopenpasswords = ${KK_OFFICE_DOCUMENTOPENPASSWORD:true}

# Excel文档(xlsx)的前端解析方式，默认为web（Web端解析）
# web: 使用前端SheetJS库解析，减轻服务器压力
# image: 服务器转换为图片，兼容性更好
office.type.web = ${KK_OFFICE_TYPE_WEB:web}

# Office文档预览类型
# 支持动态配置，可选值：image/pdf，默认使用pdf模式
office.preview.type = ${KK_OFFICE_PREVIEW_TYPE:pdf}

# 是否关闭Office预览模式切换开关，默认为true（关闭切换）
# 设置为false时，用户可以在图片和PDF模式间切换
office.preview.switch.disabled = ${KK_OFFICE_PREVIEW_SWITCH_DISABLED:true}


###############################################################################
# 三、CAD文件处理配置（支持动态配置）
###############################################################################

# CAD文件预览类型
#   svg: 转换为SVG矢量格式（缩放不失真）
#   pdf: 转换为PDF格式（便于打印和标注）
cad.preview.type = ${KK_CAD_PREVIEW_TYPE:svg}

# Cad转换模块设置(aspose-cad=1 ,cadviewer=3) 
# aspose-cad 默认集成到系统,但是特别吃服务器性能  (支持转换格式为 svg、pdf)
# cadviewer 下载地址 https://cadviewer.com/alldownloads/autoxchange/ 更具自己系统下载转换包(支持转换格式为 svg、svgz、pdf)
# 1=aspose-cad  转换格式为 pdf,svg,tif   支持类型最多
# 2=cadviewer   转换格式为 pdf,svg  支持的类型 dwg  dxf  dwf
cad.conversionmodule = 1

# Cad 后端转换包路径 （linux 严格注意大小写）
# cadviewer windows 修改名称为 cadviewer.exe   inux修改名称为  cadviewer   需要安装字体 
# cadviewer 字体下载 https://cadviewer.com/downloads/fonts/fonts.tar.gz  放在 cad.file.path 目录里面的fonts.
cad.cadconverterpath  = false


# CAD文件处理线程数
cad.thread = ${KK_CAD_THREAD:5}

# CAD文件处理超时时间（秒）
cad.timeout = ${KK_CAD_TIMEOUT:90}


###############################################################################
# 四、PDF文件处理配置（支持动态配置）
###############################################################################

# 是否禁止PDF演示模式，默认为true（禁止）
pdf.presentationMode.disable = ${KK_PDF_PRESENTATION_MODE_DISABLE:true}

# 是否禁止PDF文件菜单中的"打开文件"选项，默认为true（禁止）
pdf.openFile.disable = ${KK_PDF_OPEN_FILE_DISABLE:true}

# 是否禁止PDF打印功能，默认为true（禁止）
pdf.print.disable = ${KK_PDF_PRINT_DISABLE:true}

# 是否禁止PDF下载功能，默认为true（禁止）
pdf.download.disable = ${KK_PDF_DOWNLOAD_DISABLE:true}

# 是否禁止PDF书签/大纲功能，默认为true（禁止）
pdf.bookmark.disable = ${KK_PDF_BOOKMARK_DISABLE:true}

# 是否禁止PDF编辑功能（注释、表单等），默认为false（允许编辑）
pdf.disable.editing = ${KK_PDF_DISABLE_EDITING:false}

# PDF处理最大线程数，控制并发处理能力
pdf.max.threads = 10

# PDF处理超时配置
pdf.timeout.small = 90
pdf.timeout.medium = 180
pdf.timeout.large = 300
pdf.timeout.xlarge = 600

# PDF智能DPI优化
# 是否启用PDF DPI智能调整，默认为true（启用）
# 根据PDF页数自动调整DPI，平衡清晰度和性能
pdf.dpi.enabled = true

# PDF转图片的基准DPI，默认为144
# 当DPI优化禁用时使用此值
pdf2jpg.dpi = ${KK_PDF2JPG_DPI:144}

# 智能DPI分级配置
# 小文件（0-50页）：150 DPI（高质量）
pdf.dpi.small = 150
# 中等文件（50-100页）：120 DPI（平衡质量与性能）
pdf.dpi.medium = 120
# 大文件（100-200页）：96 DPI（优化性能）
pdf.dpi.large = 96
# 超大文件（200-500页）：72 DPI（快速转换）
pdf.dpi.xlarge = 72
# 巨量文件（>500页）：72 DPI（最小资源消耗）
pdf.dpi.xxlarge = 72


###############################################################################
# 五、TIF文件处理配置（支持动态配置）
###############################################################################

# TIF文件预览类型
#   tif: 使用前端Tiff.js插件直接浏览（需要浏览器支持）
#   jpg: 服务器转换为JPG格式后显示
#   pdf: 服务器转换为PDF格式显示
tif.preview.type = ${KK_TIF_PREVIEW_TYPE:tif}

# TIF文件处理线程数
tif.thread = 5

# TIF文件处理超时时间（秒）
tif.timeout = 90


###############################################################################
# 六、媒体文件处理配置（支持动态配置）
###############################################################################

# 媒体文件类型（音频、视频）
media = ${KK_MEDIA:mp3,wav,mp4,flv,mpd,m3u8,ts,mpeg,m4a}

# 需要转换的媒体文件类型
convertMedias = ${KK_CONVERTMEDIAS:avi,mov,wmv,mkv,3gp,rm,mpeg}

# 媒体文件超时控制
media.timeout.enabled = true
media.small.file.timeout = 30
media.medium.file.timeout = 60
media.large.file.timeout = 180
media.xl.file.timeout = 300
media.xxl.file.timeout = 600
media.xxxl.file.timeout = 1200

# 媒体文件转换最大大小（MB）
media.convert.max.size = 300

# 是否禁用视频格式转换功能，默认为false（禁用）
# ⚠️ 重要：视频转换非常消耗CPU和内存资源
media.convert.disable = ${KK_MEDIA_CONVERT_DISABLE:false}


###############################################################################
# 七、文件存储与缓存配置（支持动态配置）
###############################################################################

# 预览生成资源的存储路径，默认为应用根路径下的file目录
# Windows示例：D:\\kkFileview\\（注意双反斜杠）
# Linux示例：/opt/kkfileview/file/
# 重要：确保应用有该目录的读写权限
file.dir = ${KK_FILE_DIR:default}

# 允许预览的本地文件夹路径，默认为default（禁止所有本地文件预览）
# ⚠️ 安全警告：配置此路径可能允许访问系统文件，请谨慎配置
# Windows示例（注意前面加反斜杠）：\D:\\kkFileview\\1\\1.txt
# Linux示例（注意前面加正斜杠）：/opt/1.txt
# 使用file协议访问：file://d:/1/1.txt（Windows）或 file:/opt/1/1.txt（Linux）
local.preview.dir = ${KK_LOCAL_PREVIEW_DIR:default}

# 是否启用缓存，支持动态配置
# 默认true，开启缓存提高性能
cache.enabled = ${KK_CACHE_ENABLED:true}

# 缓存实现类型，默认为jdk（使用JDK内置对象实现）
# 可选值：
#   jdk: JDK内置ConcurrentHashMap，单机部署推荐
#   redis: Redis分布式缓存，集群部署推荐
#   default: 内嵌RocksDB，支持持久化
cache.type = ${KK_CACHE_TYPE:jdk}

# Redis部署模式，默认为single（单机模式）
# 可选值：
#   single: 单机模式（默认）
#   cluster: 集群模式
#   sentinel: 哨兵模式（高可用）
#   master-slave: 主从模式
spring.redisson.mode = single
# Redis连接地址，支持多种格式：
# 单机模式：redis://127.0.0.1:6379
# 集群模式：redis://node1:6379,redis://node2:6379,redis://node3:6379
# 哨兵模式：redis://sentinel1:26379,redis://sentinel2:26379
spring.redisson.address = ${KK_SPRING_REDISSON_ADDRESS:redis://127.0.0.1:6379}
# Redis连接密码，无密码时留空
spring.redisson.password = ${KK_SPRING_REDISSON_PASSWORD:}
# Redis数据库索引，默认为0（0-15）
# 不同业务可使用不同数据库隔离
spring.redisson.database = ${KK_SPRING_REDISSON_DATABASE:0}

# 缓存清理配置
# 是否启用缓存自动清理，默认为true（启用）
# 定期清理过期缓存，避免磁盘空间无限增长
cache.clean.enabled = ${KK_CACHE_CLEAN_ENABLED:true}
# 缓存自动清理时间，使用Quartz cron表达式，默认为每天凌晨3点执行
# 表达式格式：秒 分 时 日 月 周 年（可选）
# 0 0 3 * * ? 表示每天3:00:00执行清理
cache.clean.cron = ${KK_CACHE_CLEAN_CRON:0 0 3 * * ?}


###############################################################################
# 八、安全与访问控制配置（支持动态配置）
###############################################################################

# 提供预览服务的地址，默认从请求url读，如果使用nginx等反向代理，需要手动设置
# base.url = https://file.keking.cn
base.url = ${KK_BASE_URL:default}

# 信任站点白名单配置，多个用','隔开
# ⚠️ 安全提示：为防止SSRF攻击，强烈建议配置信任主机白名单
# ⚠️ 如果不配置，系统将默认拒绝所有外部文件预览请求
# 配置示例：
# trust.host = kkview.cn,yourdomain.com,cdn.example.com
# 如果需要允许所有域名（不推荐，仅用于测试环境），请设置为：
# trust.host = *
# 当前配置：默认本机测试 （正式启用请修改）
trust.host = ${KK_TRUST_HOST:default}

# 不信任站点黑名单配置，多个用逗号隔开
# 黑名单优先级高于白名单，设置后将禁止预览来自这些站点的文件
# 建议配置：禁止访问内网地址和本地地址，防止内部信息泄露
# 配置示例：
# not.trust.host = localhost,127.0.0.1,0.0.0.0,192.168.*,10.*,172.16.*,172.17.*,172.18.*,172.19.*,172.20.*,172.21.*,172.22.*,172.23.*,172.24.*,172.25.*,172.26.*,172.27.*,172.28.*,172.29.*,172.30.*,172.31.*
not.trust.host = ${KK_NOT_TRUST_HOST:default}

# 禁止访问的文件类型，安全限制
# 支持动态配置，格式：exe,dll,dat
prohibit = ${KK_PROHIBIT:exe,dll,dat}

# 是否忽略SSL证书验证，默认为true（忽略）
# 用于开发环境或自签名证书场景
# 生产环境建议设置为false，启用完整的证书验证
kk.ignore.ssl = false

# 是否启用URL重定向功能，默认为true（启用）
# 用于处理文件下载、外部资源引用等场景
kk.enable.redirect = false


###############################################################################
# 九、水印配置（支持动态配置）
###############################################################################

# 水印文本内容
# 可以通过环境变量 WATERMARK_TXT 覆盖
watermark.txt = ${WATERMARK_TXT:}

# 水印X轴间距
# 可以通过环境变量 WATERMARK_X_SPACE 覆盖
watermark.x.space = ${WATERMARK_X_SPACE:10}

# 水印Y轴间距
# 可以通过环境变量 WATERMARK_Y_SPACE 覆盖
watermark.y.space = ${WATERMARK_Y_SPACE:10}

# 水印字体
# 可以通过环境变量 WATERMARK_FONT 覆盖
watermark.font = ${WATERMARK_FONT:微软雅黑}

# 水印字体大小
# 可以通过环境变量 WATERMARK_FONTSIZE 覆盖
watermark.fontsize = ${WATERMARK_FONTSIZE:18px}

# 水印颜色
# 可以通过环境变量 WATERMARK_COLOR 覆盖
watermark.color = ${WATERMARK_COLOR:black}

# 水印透明度，0.0-1.0
# 可以通过环境变量 WATERMARK_ALPHA 覆盖
watermark.alpha = ${WATERMARK_ALPHA:0.2}

# 水印宽度
# 可以通过环境变量 WATERMARK_WIDTH 覆盖
watermark.width = ${WATERMARK_WIDTH:180}

# 水印高度
# 可以通过环境变量 WATERMARK_HEIGHT 覆盖
watermark.height = ${WATERMARK_HEIGHT:80}

# 水印旋转角度
# 可以通过环境变量 WATERMARK_ANGLE 覆盖
watermark.angle = ${WATERMARK_ANGLE:10}


###############################################################################
# 十、FTP文件访问配置（支持动态配置）
###############################################################################

# FTP模块设置
# 预览源为FTP时，可在ftp url后面加参数?ftp.username=ftpuser&ftp.password=123456&ftp.control.encoding=GBK,指定,不指定默认用配置的 (为了安全我们强烈建议在配置中设置相关信息)
# ftp.control.encodin (根据FTP服务器操作系统选择，Linux一般为UTF-8，Windows一般为GBK)
# 使用方法,支持,分割第一个是域名或者IP地址后面是用户名在后面是密码,在后面是编码(用户名密码和编码用:分割, 域名用,分割),切记url不需要任何协议头
# ftp.username = 地址:端口:用户名:密码:编码,192.168.0.2:21:name:123456:UTF-8,www.xxx.com:21:admin:pass:UTF-8  多客户端,分割
# ftp.username =10.99.1.2:21:666:88888:GBK
ftp.username = false


###############################################################################
# 十一、首页与文件管理配置（支持动态配置）
###############################################################################

# 是否禁用首页文件上传功能，默认为true（禁用）
# 设置为true可关闭上传功能，仅用于预览
file.upload.disable = true

# 网站备案信息，显示在首页底部，默认为空
beian = ${KK_BEIAN:default}

# 首页初始化加载的页码，默认为1（第一页）
home.pagenumber = ${DEFAULT_HOME_PAGENUMBER:1}

# 首页每页显示的文件数量，默认为20
home.pagesize = ${DEFAULT_HOME_PAGSIZE:20}

# 文件删除验证配置
# 是否启用验证码验证删除文件，默认为false（不启用）
# 启用后删除文件需要输入验证码，防止误删
delete.captcha = ${KK_DELETE_CAPTCHA:false}

# 删除文件密码，默认为123456
delete.password = ${KK_DELETE_PASSWORD:123456}

# 是否删除转换后的源文件，默认为true（删除）
# 启用可节约磁盘空间，但会丢失原始文件
delete.source.file = ${KK_DELETE_SOURCE_FILE:true}


###############################################################################
# 十二、权限与认证配置（支持动态配置）
###############################################################################

# 是否启用图片预览权限，默认为true（启用）
# 设置为false可禁用所有图片预览功能
kk.Picturespreview = true

# 是否启用跨域文件获取权限，默认为true（启用）
kk.Getcorsfile = true

# 是否启用添加异步任务权限，默认为true（启用）
# 大文件转换通常使用异步任务处理
kk.addTask = true

# API密钥功能，默认为false（禁用）
# 启用后需要提供密钥才能调用API
kk.key = false

# AES加密密钥，必须为16位字符
# 启用AES加密时，接入方需使用相同的密钥
# 用于敏感数据传输加密
aes.key = 1234567890123456

# Basic认证配置，格式：域名:用户名:密码，多个用逗号分隔
# 用于保护特定域名的访问
# 示例：192.168.0.1:admin:pass123,example.com:user:pass456
basic.name = false

# User-Agent验证字符串，默认不启用
# 可用于简单的客户端验证
useragent = false


###############################################################################
# 十三、高级功能与兼容性配置（支持动态配置）
###############################################################################

# 异步配置刷新定时时间（秒）
kk.refreshschedule = 2

# 首页是否显示AES密钥 默认为false（禁用）
kk.isshowaeskey = false

# 是否允许XLSX编辑
kk.xlsxallowedit = false

# 是否显示XLSX工具栏
kk.xlsxshowtoolbar = false

# 首页是否显示key密钥 默认为false（禁用）
kk.isshowkey = false

# 预览html文件 是否启用JavaScript 默认为true（启用）
kk.scriptjs = true


###############################################################################
# 十四、文件类型分类配置（支持动态配置）
###############################################################################

# 纯文本文件类型，直接显示
simText = ${KK_SIMTEXT:txt,html,htm,asp,jsp,xml,json,properties,md,gitignore,log,java,py,c,cpp,sql,sh,bat,m,bas,prg,cmd}

前端使用

普通文件地址预览

适用于系统已经直接暴露出可下载文件地址的情况。前端只需要编码后打开新窗口。

1
2
var url = 'http://127.0.0.1:8080/file/test.txt';
window.open('https://file.kkview.cn/onlinePreview?url=' + encodeURIComponent(base64Encode(url)));

流式接口预览

很多业务系统通过 fileId、code 等参数走统一下载接口，此时原始 URL 没有后缀名，需要额外指定完整文件名。

1
2
3
var originUrl = 'http://127.0.0.1:8080/filedownload?fileId=1';
var previewUrl = originUrl + '&fullfilename=test.txt';
window.open('https://file.kkview.cn/onlinePreview?url=' + encodeURIComponent(Base64.encode(previewUrl)));

FTP 资源预览

FTP 如果允许匿名访问，可以直接预览；如果需要认证，则把连接参数拼到 URL 后面传入。

1
2
3
4
5
6
7
8
// 匿名 FTP
var url = 'ftp://127.0.0.1/file/test.txt';
window.open('https://file.kkview.cn/onlinePreview?url=' + encodeURIComponent(Base64.encode(url)));

// 认证 FTP
var originUrl = 'ftp://127.0.0.1/file/test.txt';
var previewUrl = originUrl + '?ftp.control.port=21&ftp.username=admin&ftp.password=123456&ftp.control.encoding=utf8';
window.open('https://file.kkview.cn/onlinePreview?url=' + encodeURIComponent(Base64.encode(previewUrl)));

带 Basic 鉴权的 HTTP 资源

如果文件源本身需要用户名和密码，可以直接把 Basic 鉴权参数拼到地址中，再交给 kkFileView。

1
2
3
var originUrl = 'http://127.0.0.1/file/test.txt';
var previewUrl = originUrl + '?basic.name=admin&basic.pass=123456';
window.open('https://file.kkview.cn/onlinePreview?url=' + encodeURIComponent(Base64.encode(previewUrl)));

前后端同秘钥加密接入

如果不希望明文传递原始文件地址，可以在前端先做 AES 加密，再通过 encryption=aes 告知服务端按 AES 方式解密。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
<script src="https://file.kkview.cn/js/crypto-js.js"></script>
<script src="https://file.kkview.cn/js/aes.js"></script>

function aesEncrypt(encryptString, key) {
  var keyBytes = CryptoJS.enc.Utf8.parse(key);
  var srcs = CryptoJS.enc.Utf8.parse(encryptString);
  var encrypted = CryptoJS.AES.encrypt(srcs, keyBytes, {
    mode: CryptoJS.mode.ECB,
    padding: CryptoJS.pad.Pkcs7
  });
  return encrypted.toString();
}

var key = '1234567890123456';
var url = 'http://127.0.0.1/file/test.txt';
window.open('https://file.kkview.cn/onlinePreview?url=' + encodeURIComponent(aesEncrypt(url, key)) + '&encryption=aes');

常见问题

预览乱码

大部分Linux系统上并没有预装中文字体或字体不全，需要把常用字体拷贝到Linux服务器上，具体操作如下：

  • 下载字体包 https://kkview.cn/resource/fonts.zip
  • 文件解压完整拷贝到Linux下的 /usr/share/fonts 目录。
  • 然后依次执行以下命令使字体生效
    • mkfontscale
    • mkfontdir
    • fc-cache

示例

]]> https://blog.zhangsifan.com/posts/20221021ov/ 2022-10-20T16:00:00.000Z kkFileView为文件文档在线预览解决方案，该项目使用流行的spring boot搭建，易上手和部署，基本支持主流办公文档的在线预览，如doc,docx,xls,xlsx,ppt,pptx,pdf,txt,zip,rar,图片,视频,音频等等 利用 kkFileView 实现在线预览文件 2022-10-20T16:00:00.000Z JCAlways WPS WebOffice 提供了网页版的 Office 文档在线查看与编辑能力，通过官方 JS-SDK 可以在浏览器中打开 WPS 文档，并支持在线编辑、保存、打印等操作。整体流程为：下载 JS-SDK → 引用 SDK → 后端提供文档链接与 token → 前端初始化。

相关链接

下载 JS-SDK

在使用之前，请先下载最新版本的 js-sdk 代码。

引用 JS-SDK

  • 非模块化
1
<script src="web-office-sdk.umd.js"></script>
  • CommonJS 规范
1
let WebOfficeSDK = require("./web-office-sdk.cjs.js");
  • 非模块化
1
import WebOfficeSDK from "./web-office-sdk.es.js";

使用

核心步骤说明：

  1. WebOfficeSDK.config({ url, mount })：初始化 SDK，url 为后端提供的文档地址，mount 指定挂载的 DOM 元素
  2. wps.setToken({ token, timeout })：设置鉴权 token，timeout 为 token 有效期（毫秒），到期后需重新设置
  3. 需在 onMounted 中调用，确保挂载容器已渲染完成
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
<template>
  <div class="wps"><div class="custom-mount"></div></div>
</template>
<script setup lang="ts">
import { onMounted } from "vue";
import WebOfficeSDK from './web-office-sdk.es.js';
const init = async () => {
  const url = ''; // 后端提供的链接
  const token = "";
  const wps = WebOfficeSDK.config({
    url: url,
    mount: document.querySelector(".custom-mount")!,
  });
  wps.setToken({
    token: token,
    timeout: 10000,
  });
};
onMounted(() => {
  init();
});
</script>
<style lang="less" scoped>
.wps {
  width: 100%;
  height: 900px;
  background-color: #66ccff;
  .custom-mount {
    width: 100%;
    height: 100%;
  }
}
</style>
]]> https://blog.zhangsifan.com/posts/20221010bg/ 2022-10-09T16:00:00.000Z 使用WPS WEB Office,可以在浏览器中打开WPS Office文档,并且可以在线编辑,保存,打印等操作,本文将介绍如何在前端使用WPS WEB Office. WPS WEB Office 前端使用教程 2022-10-09T16:00:00.000Z JCAlways Element Plus 的 el-upload 组件默认只支持选择文件，通过操作其内部 <input> 的 webkitdirectory 属性，可以开启选择整个文件夹上传的功能，并且可以选择文件夹或单个文件两种模式切换。

实现思路

el-upload 内部隐藏了一个 <input type="file">，通过 document.querySelector(".el-upload__input") 获取该元素，动态设置 webkitdirectory 属性即可切换文件夹选择模式：

  • webkitdirectory = true：选择文件夹（会展开该目录下所有文件）
  • webkitdirectory = false：选择单个文件

代码

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
<template>
  <el-upload
    multiple
    action="http://192.168.1.8:3030/file/upload"
    :auto-upload="false"
    :show-file-list="false"
    :on-change="handleChange"
  >
    <template #trigger>
      <el-button type="primary" @click="folderMode(false)">上传文件</el-button>
      <el-button type="primary" @click="folderMode(true)">上传文件夹</el-button>
    </template>
  </el-upload>
</template>
<script setup lang="ts">
import { reactive, onMounted, nextTick } from "vue";
import type { UploadFile, UploadFiles } from "element-plus";
const state = reactive({
  uploadEle: null as Element | null,
  uploadList: [],
});
const folderMode = (type: boolean) => {
  if (state.uploadEle) {
    state.uploadEle.webkitdirectory = type;
  }
};
const handleChange = async (
  uploadFile: UploadFile,
  uploadFiles: UploadFiles
) => {
  console.log(uploadFile, uploadFiles);
};
onMounted(() => {
  nextTick(() => {
    state.uploadEle = document.querySelector(".el-upload__input");
  });
});
</script>
<style lang="less" scoped></style>

代码说明

  • onMounted 中通过 nextTick 等待组件渲染完成后，用 .el-upload__input 拿到内部文件选择框
  • folderMode(true) / folderMode(false) 两个按钮分别切换「上传文件夹」和「上传文件」模式
  • handleChange 中 uploadFiles 是本次选择的文件列表，文件夹模式下会包含所有子文件，可在此进行上传处理

示例

]]> https://blog.zhangsifan.com/posts/20220915up/ 2022-09-14T16:00:00.000Z 为 El-upload 组件 开启文件夹上传功能 El-upload 开启上传文件夹功能 2022-09-14T16:00:00.000Z JCAlways 官方文档

vuedraggable 是基于 Sortable.js 的 Vue 拖拽排序组件，支持列表拖拽排序、跨列表拖拽、拖拽动画等能力，Vue3 版本使用 @next 标签安装。

安装

1
2
3
yarn add vuedraggable@next

npm i -S vuedraggable@next

使用

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
<template>
  <draggable
    :list="state.form_list"
    ghost-class="ghost"
    :force-fallback="true"
    chosen-class="chosenClass"
    animation="200"
    @start="onStart"
    @end="onEnd"
  >
    <template #item="{ element, index }">
      <div class="item_box">{{ element }}{{ index }}</div>
    </template>
  </draggable>
</template>
<script setup lang="ts">
import draggable from "vuedraggable";
import { reactive, onMounted } from "vue";

const state = reactive({
  form_list: [{ title: "肯德基" }, { title: "麦当劳" }],
});
//开始拖拽事件
const onStart = () => {};
//结束拖拽事件
const onEnd = () => {};
onMounted(() => {});
</script>
<style lang="less" scoped></style>

属性说明

属性说明
list绑定拖拽排序的数组，拖拽结束后会自动更新顺序
animation拖拽动画时长（ms）
ghost-class拖拽时占位元素的 class
chosen-class被选中元素的 class
force-fallback强制使用 fallback 拖拽模式（移动端兼容）
@start / @end拖拽开始 / 结束事件

拖拽结束（@end）后 list 数组顺序已被组件自动更新，直接使用即可，无需手动处理排序逻辑。

示例

]]> https://blog.zhangsifan.com/posts/20220909px/ 2022-09-08T16:00:00.000Z vue.draggable vue3-拖拽排序组件 vue.draggable vue3-拖拽排序组件 2022-09-08T16:00:00.000Z JCAlways 在 Vue3 项目中使用高德地图 JSAPI 2.0，官方推荐通过 @amap/amap-jsapi-loader 按需加载地图脚本。本文介绍从申请 Key 到封装组件的完整流程。

官方文档

申请高德 Key

  1. 打开 高德开放平台 并登录
  2. 创建应用，服务平台选择「Web端（JS API）」
  3. 获取 Key 与安全密钥（新版需要配置代理服务或安全密钥，用于 JSAPI 2.0 鉴权）

安装 Loader

1
npm i @amap/amap-jsapi-loader

使用

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
<!-- MyMap.vue -->
<template>
  <div :id="state.id"></div>
</template>
<script setup lang="ts">
import { onMounted, reactive } from "vue";
import AMapLoader from "@amap/amap-jsapi-loader";
const props = defineProps({
  modelValue: null, // 坐标
});
const state = reactive({
  id: "",
  map: null as any,
});
const initMap = () => {
  state.id =
    Math.random().toString(36).substring(7) + Math.floor(Math.random() * 100);
  AMapLoader.load({
    key: "", // 申请好的Web端开发者Key，首次调用 load 时必填
    version: "2.0", // 指定要加载的 JSAPI 的版本
    plugins: ["AMap.Scale", "AMap.Marker"], // 需要使用的的插件列表
  })
    .then((AMap) => {
      state.map = new AMap.Map(state.id, {
        //设置地图容器id
        viewMode: "3D", //是否为3D地图模式
        zoom: 18, //初始化地图级别
        center: props.modelValue, //初始化地图中心点位置
        doubleClickZoom: false, // 禁止双击放大地图
        layers: [],
      });
      if (state.map) {
        //   比例尺
        const scale = new AMap.Scale({
          visible: true,
        });
        state.map.addControl(scale);
        // 点
        const marker = new AMap.Marker({
          position: props.modelValue,
        });
        state.map.add(marker);
      }
    })
    .catch((e) => {
      console.log(e);
    });
};
onMounted(() => {
  initMap();
});
</script>
<style lang="less" scoped>
#container {
  padding: 0px;
  margin: 0px;
  width: 100%;
  height: 800px;
}
</style>

代码说明

  • 随机容器 id：每次初始化生成随机 id 并作为容器，避免多实例（如列表循环）时 id 冲突导致地图渲染异常
  • AMapLoader.load：按需加载 JSAPI 脚本，key 填入申请到的 Web 端 Key，version 指定版本，plugins 声明需要使用的插件
  • new AMap.Map：创建地图实例，center 传入经纬度数组（如 [116.39, 39.9]），viewMode: "3D" 开启 3D 视角
  • AMap.Scale / AMap.Marker：通过 addControl 添加比例尺，通过 add 在地图上添加标记点

页面中使用

1
2
3
<template>
  <MyMap v-model="[116.397428, 39.90923]" />
</template>

注意：AMap.Map 必须在容器已挂载且有宽高后创建，因此初始化逻辑放在 onMounted 中执行；如果容器是异步渲染（如弹窗），需要等 DOM 渲染完成后（nextTick）再调用。

]]> https://blog.zhangsifan.com/posts/20220905ap/ 2022-09-04T16:00:00.000Z Vue3 使用高德地图 JSAPI 2.0 的完整教程：申请 Key、安装 Loader、封装地图组件 Vue3使用高德地图 2022-09-04T16:00:00.000Z JCAlways 官方文档

NProgress 是一个轻量的页面顶部加载进度条库，常用于 SPA 路由切换、Ajax 请求时提示用户”页面正在加载”。它依赖 requestAnimationFrame 自动添加过渡动画，体积小、无依赖。

安装

1
npm install nprogress

使用

1
2
3
4
5
6
7
8
9
10
11
import "nprogress/nprogress.css";
import NProgress from "nprogress";
NProgress.configure({ showSpinner: false });
// 显示进度条
NProgress.start();
// 隐藏进度条
NProgress.done();

NProgress.set(0.0);     // Sorta same as .start()
NProgress.set(0.4);
NProgress.set(1.0);     // Sorta same as .done()

在 Vue Router 中使用

1
2
3
4
5
6
7
router.beforeEach((to, from, next) => {
  NProgress.start(); // 路由跳转前显示进度条
  next();
});
router.afterEach(() => {
  NProgress.done(); // 跳转完成后关闭
});

常用配置

1
2
3
4
5
6
7
NProgress.configure({
  showSpinner: false, // 关闭右上角加载图标
  minimum: 0.1, // 起始最小百分比
  easing: "ease", // 动画缓动方式
  speed: 200, // 动画速度
  trickleSpeed: 200, // 自动递增间隔
});

API 一览

方法说明
NProgress.start()开始显示进度条，从 0 开始自动递增
NProgress.done()进度到 100% 并隐藏进度条
NProgress.set(n)手动设置进度值（0 ~ 1）
NProgress.inc(n?)按指定量递增（默认随机小增量）
NProgress.configure(obj)全局配置（是否显示 spinner、动画参数等）

自定义进度条样式

NProgress 默认显示在页面顶部，可通过 CSS 修改 #nprogress .bar 的高度与颜色，使其融入站点主题：

1
2
3
4
#nprogress .bar {
  background: #409eff; /* 改为站点主题色 */
  height: 3px;
}

CodePen 示例

]]> https://blog.zhangsifan.com/posts/20220903nr/ 2022-09-02T16:00:00.000Z Nprogress使用教程 Nprogress使用教程 2022-09-02T16:00:00.000Z JCAlways 官方网站

FingerprintJS 是一个浏览器指纹识别库，通过采集浏览器环境信息（UA、Canvas、WebGL、字体、时区等）生成稳定的 visitorId，可用于无感防刷、风险控制、账号安全等场景。

安装

1
npm i @fingerprintjs/fingerprintjs

使用

1
2
3
4
5
6
7
8
9
10
11
import FingerprintJS from "@fingerprintjs/fingerprintjs";

const getFingerPrintID =  async () => {
    const fpPromise = await FingerprintJS.load();
    const result = await fpPromise.get();
    return result.visitorId;
},

setTimeout(() => {
    console.log(await getFingerPrintID())
}, 1000);

代码说明

  • FingerprintJS.load()：加载指纹计算模块，只需加载一次，可存入 Promise 复用
  • fpPromise.get()：返回指纹结果对象，其中 visitorId 即为该浏览器的唯一标识
  • 同一浏览器在不同时间、不同页面获取的 visitorId 保持一致，但清除浏览器数据或更换设备后可能变化

应用场景

  • 无感登录：记录用户首次访问生成的 visitorId，下次访问自动识别老用户
  • 防刷验证：投票、抽奖、评论等场景通过 visitorId 限制同一设备操作次数
  • 风控识别：检测批量注册、撞库、爬虫等异常行为

Cookie 存储在浏览器本地，用户清除浏览器数据后即失效，且可被隐私模式拦截；而 FingerprintJS 通过硬件与浏览器环境特征生成标识，即使清除 Cookie 也能再次识别，稳定性更高。

CodePen 示例

]]> https://blog.zhangsifan.com/posts/20220903sg/ 2022-09-02T16:00:00.000Z Fingerprintjs使用教程 Fingerprintjs使用教程 2022-09-02T16:00:00.000Z