第 1 周：认识 Blender

1. Day 1：认识界面、主要编辑器和工作区。
2. Day 2：练习旋转、缩放和平移视图。
3. Day 3：选择、隐藏和删除物体。
4. Day 4：使用 G 键和坐标轴移动物体。
5. Day 5：使用 R 键旋转物体。
6. Day 6：使用 S 键缩放物体。
7. Day 7：制作简单桌面场景，重复上述操作。

验收：不看教程，能够创建、移动、旋转、缩放和删除物体。

第 2 周：模型基础

1. Day 8：切换对象模式与编辑模式。
2. Day 9：认识顶点、边、面并练习选择。
3. Day 10：编辑网格，简单修改模型形状。
4. Day 11：了解细分等修改器。
5. Day 12：创建材质并为模型设置颜色。
6. Day 13：认识纹理及 PNG 贴图的作用。
7. Day 14：创建并保存一个带材质的模型。

验收：理解模型、材质和贴图之间的关系。

第 3 周：导入自己的 PMX 模型

1. Day 15：认识 PMX 文件、贴图文件和骨骼结构。
2. Day 16：按当前 Blender 版本安装兼容的 MMD Tools。
3. Day 17：导入自己的 PMX 角色模型。
4. Day 18：检查角色贴图是否正确显示。
5. Day 19：认识 Mesh 和 Armature。
6. Day 20：找到头部、手臂等骨骼。
7. Day 21：保存完整的角色工程，并记录缺失或异常的资源。

验收：角色在 Blender 中正常显示，能够查看骨骼结构。如果导入失败，先排查插件版本、贴图路径和模型文件，再继续后续课程。

第 4 周：动画基础

1. Day 22：认识 Timeline。
2. Day 23：用关键帧制作简单移动动画。
3. Day 24：制作旋转动画。
4. Day 25：比较不同的动画插值方式。
5. Day 26：使用 Dope Sheet 编辑关键帧。
6. Day 27：认识 Shape Keys。
7. Day 28：制作并保存一个简单循环动画。

验收：独立制作一个简单的关键帧动画。

第 5 周：角色骨骼

1. Day 29：理解 Armature 骨骼系统。
2. Day 30：使用 Pose Mode 调整角色姿势。
3. Day 31：控制头部骨骼，让角色转头。
4. Day 32：调整颈部骨骼，做出自然歪头。
5. Day 33：控制上半身骨骼。
6. Day 34：控制手臂，制作挥手姿势。
7. Day 35：保存三种可复用的角色姿势。

验收：角色能够转头、歪头和抬手。

第 6 周：角色面部表情

1. Day 36：检查 PMX 模型现有的面部 Morph。
2. Day 37：寻找眼球骨骼或其他眼睛控制方式。
3. Day 38：制作眨眼动作。
4. Day 39：制作微笑表情。
5. Day 40：制作惊讶表情。
6. Day 41：调整表情之间的过渡。
7. Day 42：保存三种表情动画。

验收：角色能够眨眼、微笑和表现惊讶。若模型缺少对应 Morph，先检查已有控制器；必要时调整这一周的目标。

第 7 周：角色待机动画

1. Day 43：观察角色自然站立时的姿势与重心。
2. Day 44：制作轻微呼吸动作。
3. Day 45：增加左右重心变化。
4. Day 46：加入小幅头部摆动。
5. Day 47：增加自然的手臂运动。
6. Day 48：处理循环动画的首尾关键帧。
7. Day 49：完成第一版待机动画。

验收：角色能够自然循环待机约 8～12 秒。

第 8 周：动画优化

1. Day 50：认识 Graph Editor 动画曲线。
2. Day 51：用缓入缓出优化头部动作。
3. Day 52：调整动作速度和节奏。
4. Day 53：避免机械式眨眼。
5. Day 54：协调头部和身体动作。
6. Day 55：修复循环边界的跳变。
7. Day 56：完成第二版待机动画。

验收：动作自然，没有明显的突然停止或跳变。

第 9 周：角色交互动画

1. Day 57：制作疑惑时的歪头动作。
2. Day 58：制作挥手动作。
3. Day 59：组合骨骼和表情，制作惊讶反馈。
4. Day 60：制作开心反馈。
5. Day 61：用 Action Editor 管理动作。
6. Day 62：整理并命名每个动画。
7. Day 63：完成可复用的角色动作库。

验收：拥有待机、歪头、挥手、惊讶等可复用动作。

第 10 周：网页模型导出

1. Day 64：了解 glTF / GLB 格式。
2. Day 65：检查模型缩放与朝向。
3. Day 66：检查材质和贴图引用。
4. Day 67：检查需要导出的 Action。
5. Day 68：导出 GLB 角色资源。
6. Day 69：在网页模型查看器或开发环境中检查骨骼、表情和动画。
7. Day 70：整理 Blender 工程、贴图和最终 GLB。

验收：GLB 能被 Three.js 读取，并保留项目需要的骨骼、表情与动画。MMD 的特殊材质和物理效果未必能完整转换，应逐项检查并记录后续网页端需要补做的效果。

一、先确定恢复目标

• RPO（恢复点目标）：最多允许丢失多长时间的数据。例如 RPO 为 15 分钟，就需要保证备份和日志归档能把数据恢复到故障前约 15 分钟以内。
• RTO（恢复时间目标）：从故障发生到服务恢复可用，最多允许多久。数据量大时，逻辑备份的导入速度往往比导出速度更需要关注。
• 恢复范围：是误删一张表、损坏一个库，还是整台实例不可用？单库 SQL 文件适合按库恢复；实例级故障还需要配置、账号、证书、插件、二进制日志等信息。
• 保留期：至少覆盖发现错误所需的时间。全量备份和二进制日志必须形成连续链，不能只保留最近一个 SQL 文件。

先写下 RPO、RTO 和恢复范围，再决定备份频率与工具。复制一份文件只是备份动作；只有恢复演练成功，才能证明方案可用。

二、几种备份方式怎么选

全量备份保存一个完整基线；增量备份只保存相对上次备份的变化；差异备份保存相对上次全量备份的变化。物理备份工具可支持页级增量；MySQL 二进制日志则可记录基线之后的变更，用于时间点恢复。两者不是同一种文件格式，恢复步骤也不同。

一个可落地的例子是：每天一次全量备份，连续归档二进制日志，保留至少两轮完整备份链，并把副本放在另一台设备或对象存储中。具体间隔要由 RPO、RTO、数据量和恢复演练结果决定。备份文件应加密，密钥与备份分开保管；限制读取权限，避免把数据库密码写在命令行或备份脚本中。

三、备份前检查

先确认版本、存储引擎、二进制日志和保留期：

SELECT VERSION();
SELECT @@GLOBAL.log_bin, @@GLOBAL.gtid_mode, @@GLOBAL.binlog_expire_logs_seconds;
SELECT TABLE_NAME, ENGINE
FROM information_schema.TABLES
WHERE TABLE_SCHEMA = 'appdb' AND TABLE_TYPE = 'BASE TABLE';
SHOW BINARY LOGS;

log_bin 为 ON 才能按下文做二进制日志时间点恢复。MySQL 8.4 默认启用二进制日志，但仍应检查实际实例配置。binlog_expire_logs_seconds 必须长于需要保留的恢复窗口，并留出备份、传输及故障发现的余量；如果日志在归档前被清理，就会出现恢复缺口。

检查是否存在 MyISAM、MEMORY 等非事务表。mysqldump --single-transaction 只保证 InnoDB 等事务表在同一一致性快照中导出；它不能让非事务表自动变成一致快照。备份期间也不要对待导出的表执行 ALTER TABLE、CREATE TABLE、DROP TABLE、RENAME TABLE 或 TRUNCATE TABLE，否则导出可能失败或内容不正确。

备份账户需要与导出对象和选项相符的权限。例如表需要 SELECT，视图需要 SHOW VIEW，触发器需要 TRIGGER，事件需要 EVENT；--routines 和记录日志坐标的 --source-data 还涉及额外权限。不要为了省事长期使用管理员账户执行定时备份。

四、用 mysqldump 做单库逻辑备份

下面的 PowerShell 示例导出 appdb，并把 SQL 写到 D:/mysql-backup/appdb-full.sql。先确保备份目录存在：

New-Item -ItemType Directory -Force -Path 'D:/mysql-backup'
mysqldump --host=127.0.0.1 --user=backup_user --password --databases appdb --single-transaction --quick --routines --events --triggers --hex-blob --no-tablespaces --default-character-set=utf8mb4 --result-file='D:/mysql-backup/appdb-full.sql'
if ($LASTEXITCODE -ne 0) { throw 'mysqldump failed' }
Get-FileHash -Algorithm SHA256 'D:/mysql-backup/appdb-full.sql'

--password 不附带密码值时会交互式提示输入。--databases appdb 会在文件中包含建库与 USE 语句；--routines、--events、--triggers 分别覆盖存储程序、事件和触发器；--hex-blob 使二进制列以十六进制形式导出；--no-tablespaces 省略表空间 DDL。--quick 按行从服务器读取，适合较大表。正式脚本还应记录开始与结束时间、退出码、文件大小和校验值，并在失败时通知管理员。

Windows PowerShell 的 > 重定向可能把转储写成 UTF-16，导致 MySQL 无法正确导入，因此这里使用 --result-file。此选项会覆盖同名文件，即使导出途中报错也可能留下文件；文件存在或哈希算得出来，并不等于备份成功。应同时检查退出码并定期做完整恢复演练。

GTID 注意：mysqldump 默认的 --set-gtid-purged=AUTO 在启用 GTID 时可能把源实例所有已执行事务的 GTID 写入导出文件，即使只导出了 appdb。向已有实例导入局部备份、搭建复制或连续导入多个局部备份前，必须检查该语句和目标实例的 GTID 状态。--set-gtid-purged=OFF 适用于明确不需要保留该 GTID 集的独立数据副本，不能机械地用于所有恢复场景。

恢复单库 SQL 文件

先在隔离的空实例测试。下例的转储包含 CREATE DATABASE 和 USE，因此命令不必额外指定数据库：

mysql --host=127.0.0.1 --user=restore_user --password --execute='SOURCE D:/mysql-backup/appdb-full.sql'
if ($LASTEXITCODE -ne 0) { throw 'restore failed' }

不要在生产实例上直接试运行：转储可能包含 DROP TABLE、CREATE TABLE 和大量 INSERT。导入后至少检查表、关键记录数、视图、存储程序、触发器和事件，再运行应用的关键读写流程。可以先用以下查询查看对象是否恢复：

SHOW FULL TABLES FROM appdb;
SELECT ROUTINE_NAME, ROUTINE_TYPE
FROM information_schema.ROUTINES WHERE ROUTINE_SCHEMA = 'appdb';
SELECT TRIGGER_NAME
FROM information_schema.TRIGGERS WHERE TRIGGER_SCHEMA = 'appdb';
SELECT EVENT_NAME
FROM information_schema.EVENTS WHERE EVENT_SCHEMA = 'appdb';

记录原库与恢复库的关键业务表行数、抽样记录和应用校验结果。行数一致不能证明全部内容正确，但能发现明显漏表或漏数据。

五、全量备份加二进制日志：时间点恢复

误删数据往往在下一次全量备份前才被发现。要恢复到误操作之前，需要一份一致的基线、基线对应的二进制日志坐标，以及从该坐标到目标时间点之间连续且未损坏的日志文件。

以下示例假设源实例只承载 appdb，恢复目标是隔离的空实例。多库实例应设计实例级一致备份和全实例日志回放，不能把单库转储与全实例日志直接拼接后当作通用恢复方案。

1. 记录与备份同一时刻的日志坐标

在上面的 mysqldump 命令中额外加入 --source-data=2，并另存为一份用于时间点恢复的基线：

mysqldump --host=127.0.0.1 --user=backup_user --password --databases appdb --single-transaction --quick --routines --events --triggers --hex-blob --no-tablespaces --source-data=2 --result-file='D:/mysql-backup/appdb-pitr-base.sql'
if ($LASTEXITCODE -ne 0) { throw 'baseline dump failed' }

文件内会有一条被注释掉的 CHANGE REPLICATION SOURCE TO 语句，记录类似 SOURCE_LOG_FILE='binlog.000123', SOURCE_LOG_POS=154 的坐标。=2 让它只作记录，不会在导入时真的执行复制配置。该选项要求二进制日志已开启和相应权限；它在开始导出时可能短暂获取全局读锁。保持备份期间没有上述 DDL。

2. 保存完整的日志链

SHOW BINARY LOGS 列出当前日志文件。将基线坐标所在的文件以及之后所有需要的文件安全地归档到另一处，持续监控归档是否中断。MySQL 也支持用 mysqlbinlog --read-from-remote-server --raw --stop-never 连续拉取原始二进制日志；该进程断线后不会自动重连，必须由服务管理和监控负责重启与检查缺口。

不要在确认归档、复制从库需求和恢复窗口之前清理二进制日志。全量 SQL 文件、二进制日志、版本与配置记录应一起管理；仅有 SQL 文件无法恢复其导出之后的事务。

3. 在隔离实例回放到正确位置

先导入 appdb-pitr-base.sql。然后用 mysqlbinlog 检查日志，找出误操作事务开始前的事件边界，确认目标日志文件及位置。相比只按墙上时钟截断，按文件和事件位置更明确；不要把停止位置设在一个事务的中间。

假设基线坐标为 binlog.000123:154，误操作从 binlog.000124:8876 开始，可在 PowerShell 中先生成回放文件，再用同一个 MySQL 客户端连接导入：

mysqlbinlog --start-position=154 --stop-position=8876 --result-file='D:/mysql-backup/replay.sql' 'D:/mysql-backup/binlog.000123' 'D:/mysql-backup/binlog.000124'
if ($LASTEXITCODE -ne 0) { throw 'mysqlbinlog failed' }
mysql --binary-mode --host=127.0.0.1 --user=restore_user --password --execute='SOURCE D:/mysql-backup/replay.sql'
if ($LASTEXITCODE -ne 0) { throw 'binlog replay failed' }

--start-position 作用于列出的第一个日志文件，--stop-position 作用于最后一个。中间日志按顺序完整处理。一次生成回放文件并通过一次客户端连接导入，能避免跨日志文件的会话状态被拆断。这里使用 mysqlbinlog --result-file，避免 PowerShell 文本重定向改变文件编码。回放账户还需要执行日志事件及内部 BINLOG 语句所需的权限。

最后核对目标事务之前的数据、对象定义和应用行为。确认结果后，再按业务切换流程恢复服务；不要在未经验证的情况下覆盖原始实例。

六、物理备份和大库的选择

当 SQL 导入时间达不到 RTO 时，考虑物理备份。MySQL Enterprise Backup 的 mysqlbackup 支持 InnoDB 在线物理备份与增量备份；MySQL Shell 的 dump/load 工具则提供并行的逻辑导出与导入。选择前应测量真实数据量下的备份时间、恢复时间、磁盘占用和对业务的影响。

直接压缩或复制正在运行的 InnoDB 数据目录，不能代替了解事务与日志的一致备份工具。停机文件备份需要在服务器完全停止后保存完整数据目录及恢复所需的配置与日志，并在兼容的 MySQL 环境中演练。不要只复制某个 .ibd 文件就认为已经备份了整张表。

七、自动化和恢复演练清单

1. 每次备份记录版本、实例标识、范围、开始和结束时间、退出码、文件大小、哈希、基线日志坐标，以及备份文件存放位置。
2. 自动检查最近一次成功备份的时间、日志归档连续性、剩余空间和保留期；失败要主动告警。备份文件至少保留一份与数据库主机分离的副本。
3. 定期在隔离实例从备份完整恢复，再回放日志到选定时间点，测量实际 RTO，并检查关键业务数据和应用启动。恢复演练不能只做 SQL 文件语法检查。
4. 轮换与限制备份账户；交互输入密码或使用受保护的客户端配置，避免把明文密码写入命令行、脚本、日志和仓库。控制备份文件及解密密钥的访问权限。
5. 清理旧备份时，以整条可恢复链为单位：保留对应全量备份和从其坐标开始的全部必要日志。先确认副本与恢复演练，再清理过期文件。

常见误区

参考资料

• MySQL 8.4 手册：备份类型
• MySQL 8.4 手册：mysqldump 选项与限制
• MySQL 8.4 手册：数据库备份方法
• MySQL 8.4 手册：二进制日志时间点恢复
• MySQL 8.4 手册：mysqlbinlog
• MySQL 8.4 手册：使用 mysqlbinlog 备份日志

FineBI 是帆软推出的商业智能（BI）工具。它把数据处理、可视化分析和分享放在同一套工作流程里。对于第一次使用的人，先记住一条主线：明确问题 → 准备数据 → 制作组件 → 组合仪表板 → 分享结论。本文以 FineBI 7.x 的官方帮助文档为参考；使用其他版本时，界面名称和按钮位置可能有所不同。

先弄清几个概念

例如，“哪个地区卖得最多？”中的地区是维度，销售额是指标。把销售额按地区汇总，才能得到可比较的结果。这里的“销售额”是本文示例字段的业务名称；实际项目应先确认退款、折扣、税费等是否已经计入。

准备一份可练习的数据

可以把下面的内容保存为 orders.csv，用它练习导入和制图。每行代表一笔订单，金额单位为元。

order_id,order_date,region,product,sales_amount
O001,2026-09-01,华东,键盘,120
O002,2026-09-01,华北,鼠标,200
O003,2026-09-02,华东,鼠标,80
O004,2026-09-02,华北,键盘,90
O005,2026-09-03,华东,耳机,150
O006,2026-09-03,华北,耳机,110

上传前检查三个地方：order_date 应识别为日期，sales_amount 应识别为数值，order_id 不应重复。若一笔订单可能占多行，直接统计行数就不等于订单数，需要按订单编号去重计数。示例中每行恰好是一笔订单，因此行数为 6。

完成第一次分析

1. 进入「我的分析」，在「全部分析」中新建一个分析主题，例如「九月订单分析」。
2. 在主题中添加本地 Excel 文件或 CSV 文件。FineBI 也支持由管理员准备企业数据库中的数据；首次练习用本地文件更容易看清分析过程。
3. 检查字段类型和数据内容。确认日期、地区、金额没有导入错误，再开始制作组件。
4. 创建一个柱形图：用「地区」分组，用「销售额」做求和，比较各地区销售额。
5. 再创建一个按「订单日期」分组的趋势图，仍对「销售额」求和，观察每天的变化。
6. 新建仪表板，把两个组件放进去，写上标题，并标明数据时间范围及金额单位。保存后根据需要预览、发布或分享。

这份示例数据的销售额合计应为 750 元；华东为 350 元，华北为 400 元。按日汇总分别是 9 月 1 日 320 元、2 日 170 元、3 日 260 元。如果图表与这些数字不符，先检查金额字段是否被识别为文本、汇总方式是否选成了计数，以及是否设置了过滤条件。

:::tip[先确定问题，再选图表] 比较地区销售额，可以用柱形图；观察日期变化，可以用折线图。图表的作用是让读者更快看到差异和趋势，不必为了丰富仪表板而堆放很多图。 :::

看懂结果，比做出图更重要

从示例可以说：“这 6 笔订单中，华北销售额比华东高 50 元。”但不能据此断言“华北市场一直更好”：数据只有三天，也没有纳入订单成本、退货和更长时间的变化。写分析结论时，应同时交代指标口径、时间范围和数据范围。

分享仪表板前，还要确认查看者具有相应权限。企业数据通常由管理员维护连接与数据权限，业务人员再在获授权的数据范围内分析。若页面上缺少添加数据、发布等入口，可先检查账号权限和所用版本的操作说明。

下一步学什么

完成第一张仪表板后，可以按这个顺序继续练习：先掌握过滤与排序，再学习计算字段和分组汇总，最后尝试多个组件之间的联动与分享。每增加一步，都用一两个已知结果核对计算是否符合预期。

参考资料

• FineBI 官方：5 分钟上手 FineBI
• FineBI 官方：分析主题简介
• FineBI 官方：制作第一个组件
• FineBI 官方：分享协作概述

这份笔记适合已经写过几行 Python、想把零散语法串成一个可用脚本的人。前半部分是可以回查的语法要点与易错点，后半部分完成一个“读取 CSV 并统计学习时间”的命令行脚本。示例使用 Python 3.10 及以上版本，仅依赖标准库。

1. 值、类型与表达式

input() 的结果始终是字符串；要计算分钟数，必须先转换，并考虑非法输入：

raw = "45"  # 实际交互时可换成 input("学习了多少分钟？")
minutes = int(raw)
print(f"学习了 {minutes} 分钟")

bool("") 是 False，但 bool("False") 是 True：非空字符串为真，字符串内容不会自动解析成布尔值。

2. 容器：选对数据形状

records = [
    {"subject": "Python", "minutes": 45},
    {"subject": "英语", "minutes": 30},
]

print(records[0]["subject"])             # Python；列表索引从 0 开始
print(records[:1])                       # 返回包含第一条记录的新列表
print({row["subject"] for row in records})  # 去重后的科目集合

record["minutes"] 在键不存在时抛出 KeyError；record.get("minutes", 0) 则返回默认值 0。后者适合累计计数，但不能用默认值掩盖必须存在的输入字段。

变量存放的是对对象的引用。b = a 不会复制列表；a.copy() 只复制最外层，嵌套的字典仍被共享：

a = [{"minutes": 45}]
b = a.copy()
b[0]["minutes"] = 60
print(a[0]["minutes"])  # 60

3. 控制流与推导式

if 选择分支，for 遍历数据，continue 跳过当前轮。Python 用缩进表示代码块：

for index, record in enumerate(records, start=1):
    if record["minutes"] <= 0:
        continue
    print(f'{index}. {record["subject"]}: {record["minutes"]} 分钟')

enumerate() 同时给出序号和元素；zip(a, b) 可以并行遍历两组数据，但默认会在较短的一组结束时停止。

推导式适合简单的“筛选 + 转换”，不要把复杂的多层判断挤进一行：

long_sessions = [row for row in records if row["minutes"] >= 40]
total = sum(row["minutes"] for row in records)

第一行创建列表；第二行传给 sum() 的是生成器表达式，按需提供值，不先构造另一份列表。

4. 函数、类型标注与异常

函数用参数接收输入，用 return 交还结果。print() 只负责显示，不等于返回值。类型标注能帮助阅读和静态检查，不会自动校验运行时输入。

def total_minutes(records: list[dict[str, object]]) -> int:
    return sum(int(row["minutes"]) for row in records)

这段写法假设每条记录都有可转换的 minutes。当数据来自文件、网络或用户输入时，应先校验，再交给计算函数。也要避开可变默认参数：

def add_subject(subject: str, subjects: list[str] | None = None) -> list[str]:
    if subjects is None:
        subjects = []
    subjects.append(subject)
    return subjects

如果把默认值直接写成 []，多次调用会共享同一个列表。上面每次未传入列表时都会新建一个。

异常处理只包住可能失败的操作，并捕获预期类型：

try:
    minutes = int("四十五")
except ValueError as exc:
    print(f"分钟数无效：{exc}")

ValueError 表示值的格式不合要求；文件打不开通常表现为 OSError。不要用宽泛的 except Exception 把自己写错的代码也当成普通输入错误。

5. 文件、模块与脚本入口

pathlib.Path 处理路径，with 管理文件的打开和关闭。Path(__file__).with_name("study.csv") 指向脚本旁边的 CSV，运行命令时所在目录改变也不影响它。

from pathlib import Path

source = Path(__file__).with_name("study.csv")
with source.open("r", encoding="utf-8") as file:
    text = file.read()

if __name__ == "__main__": 用来区分“直接运行脚本”和“被其他文件导入”。把主要工作写进 main()，导入模块时就不会意外开始读文件、打印或退出。

6. 完整脚本：统计 CSV 中的学习时间

在同一个目录中创建 study.csv：

date,subject,minutes
2026-10-07,Python,45
2026-10-08,英语,30
2026-10-08,Python,25

再创建 study.py。读取函数负责把外部文本变成经过校验的记录，统计函数只做计算，main() 负责输出和退出状态：

import csv
import sys
from collections.abc import Iterable, Iterator
from dataclasses import dataclass
from datetime import date
from pathlib import Path


@dataclass(frozen=True)
class StudyRecord:
    day: date
    subject: str
    minutes: int


def read_records(path: Path) -> Iterator[StudyRecord]:
    with path.open("r", encoding="utf-8-sig", newline="") as file:
        reader = csv.DictReader(file)
        if reader.fieldnames != ["date", "subject", "minutes"]:
            raise ValueError("表头必须是 date,subject,minutes")

        for row in reader:
            line_no = reader.line_num
            if None in row:
                raise ValueError(f"第 {line_no} 行：字段数量过多")

            day_text = (row.get("date") or "").strip()
            subject = (row.get("subject") or "").strip()
            minutes_text = (row.get("minutes") or "").strip()

            try:
                day = date.fromisoformat(day_text)
            except ValueError as exc:
                raise ValueError(f"第 {line_no} 行：无效日期 {day_text!r}") from exc

            if not subject:
                raise ValueError(f"第 {line_no} 行：科目不能为空")

            try:
                minutes = int(minutes_text)
            except ValueError as exc:
                raise ValueError(f"第 {line_no} 行：分钟数不是整数 {minutes_text!r}") from exc

            if minutes <= 0:
                raise ValueError(f"第 {line_no} 行：分钟数必须大于 0")

            yield StudyRecord(day, subject, minutes)


def summarize(records: Iterable[StudyRecord]) -> dict[str, int]:
    totals: dict[str, int] = {}
    for record in records:
        totals[record.subject] = totals.get(record.subject, 0) + record.minutes
    return totals


def main() -> int:
    source = Path(__file__).with_name("study.csv")

    try:
        totals = summarize(read_records(source))
    except (OSError, ValueError) as exc:
        print(f"读取失败：{exc}", file=sys.stderr)
        return 1

    for subject, minutes in sorted(
        totals.items(), key=lambda item: (-item[1], item[0])
    ):
        print(f"{subject}：{minutes} 分钟")
    print(f"总计：{sum(totals.values())} 分钟")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

运行 python study.py，Windows 上也可以使用 py study.py。预期输出：

Python：70 分钟
英语：30 分钟
总计：100 分钟

脚本里的几个关键连接点

• 文本到对象：csv.DictReader 读到的正常单元格是字符串，缺失字段可能得到 None；date.fromisoformat() 和 int() 在入口处转换并校验。StudyRecord 的标注不会代替这一步。
• 生成器到统计函数：read_records() 中的 yield 使它按需读取。调用函数本身还没有打开文件；summarize() 遍历它时才开始读取。因此 try 要包住整个统计调用。
• 文件生命周期：完整遍历或读取函数抛错时，with 会关闭文件。如果只取生成器的前几条就停止，文件可能仍保持打开；需要显式关闭生成器，或为小文件改用列表。
• 错误到退出码：读取层知道出错行号，就抛带行号的 ValueError；main() 决定把信息写到标准错误输出并返回 1。正常完成返回 0。
• 内存使用：读取阶段不保存全部行；统计字典的大小主要由不同科目的数量决定。

7. 自测与扩展

先手动把第三行改成 2026-10-08,英语,-5：脚本应报告“第 3 行：分钟数必须大于 0”。把日期改成 2026-02-30、删除文件、清空文件内容，也能检查对应的错误分支。CSV 为空时表头缺失，脚本会报告表头错误；只有表头而没有数据时，总计是 0。

统计函数可以脱离文件单独验证。把下面的代码另存为同目录的 test_study.py，运行 python test_study.py：

from datetime import date
from study import StudyRecord, summarize

records = [
    StudyRecord(date(2026, 10, 7), "Python", 45),
    StudyRecord(date(2026, 10, 8), "Python", 25),
]
assert summarize(records) == {"Python": 70}
assert summarize([]) == {}

下一步可以写一个按日期汇总的函数。保持 read_records() 不变，只改变统计键，再比较两份汇总代码有哪些可以复用。这样练习比单纯背诵更多语法更接近实际写脚本的过程。

XML（可扩展标记语言）用标签描述有层次的数据。它规定文档如何组织；<book>、<field> 等标签的具体含义由使用 XML 的程序决定。Odoo 就用 XML 声明数据、视图、菜单和模板。

基础语法

一个 XML 文档必须有且只有一个根元素。标签区分大小写，开始和结束标签要同名、正确嵌套；没有内容的元素可以写成自闭合形式。

<?xml version="1.0" encoding="UTF-8"?>
<library>
    <book id="b1">
        <title>XML 入门</title>
        <author>小明</author>
    </book>
    <book id="b2" />
</library>

XML 声明通常放在文件开头，常见版本是 1.0，声明本身可以省略。<library> 是根元素。<book id="b2" /> 等价于 <book id="b2"></book>。<a><b></a></b> 则不合法，因为标签交叉了。

属性与注释

属性写在开始标签中；属性值必须用成对的单引号或双引号包裹，同一元素不能重复使用同一个属性名。名称不能以数字开头。实际编写时可选用字母开头，再使用字母、数字、下划线或连字符，避免与工具的命名限制冲突。

<book id="b1" language="zh-CN" available="true" />
<!-- 这是注释，不能包含连续的两个连字符 -->

XML 没有内置的布尔属性类型：这里的 "true" 首先是文本，是否当作布尔值由读取它的程序决定。

特殊字符与 CDATA

文本中的 < 和 & 必须转义；属性值中还要转义与外层引号相同的引号。五个预定义实体如下：

例如，Tom & Jerry 应写成 Tom & Jerry；<rule test="a &lt; b"> 中的比较符也需要转义。CDATA 可以在元素文本中保留大段未经转义的字符，但不能用于属性值，也不能在内部直接出现 ]]>：

<example><![CDATA[if a < b and c > d: print("ok")]]></example>

CDATA 不会让其中的内容变成 XML 子元素；解析器读到的是一段文本。

解析、遍历与添加节点

Python 标准库的 xml.etree.ElementTree 足够演示常见操作。假设 books.xml 保存了前面的 <library> 示例：

import xml.etree.ElementTree as ET

tree = ET.parse("books.xml")
root = tree.getroot()

for book in root.findall("book"):
    print(book.get("id"), book.findtext("title"))

new_book = ET.SubElement(root, "book", {"id": "b3"})
ET.SubElement(new_book, "title").text = "新书"
ET.SubElement(new_book, "author").text = "小李"
tree.write("books-updated.xml", encoding="utf-8", xml_declaration=True)

parse() 读取文件，getroot() 取得根元素，findall() 查找子节点，SubElement() 添加节点。示例中的第二本书没有 <title>，因此它的 findtext("title") 会返回 None，获取元素的属性值用get(),findtext()查找元素并返回其文本

XPath 定位节点

XPath 用路径和条件定位 XML 元素：

Python 的 ElementTree 只支持 XPath 的一个子集。从当前元素查询时通常写相对路径，例如 root.findall("./book[@id='b1']")。Odoo 的视图继承也使用 XPath 表达式定位已有视图中的节点。

Odoo 中的 XML

以下示例以 Odoo 19 的模块写法为准。Odoo XML 文件通常以 <odoo> 为根元素，按文件中的顺序执行声明；引用的记录要先定义，或者来自已在模块依赖中声明的模块。XML 文件还必须列入模块的 __manifest__.py，安装或升级模块时才会加载。

# __manifest__.py
{
    "name": "Library Demo",
    "depends": ["base"],
    "data": [
        "views/library_book_views.xml",
        "data/library_book_data.xml",
    ],
}

文件顺序有意义：后一个文件可以引用前一个文件建立的 XML ID。下面的 library.book 是示例模型，需先在模块的 Python 代码中定义 name、author 和 note 字段；仅写 XML 不会自动创建这个业务模型。

创建数据记录

record 的 model 指向要写入的 Odoo 模型，id 是该记录的 XML ID。field 用于设置字段；纯文本、ref 与 eval 分别适合普通值、已有 XML ID 和需要求值的表达式。

<?xml version="1.0" encoding="UTF-8"?>
<odoo>
    <record id="book_xml_intro" model="library.book">
        <field name="name">XML 入门</field>
        <field name="author">小明</field>
    </record>

    <record id="book_odoo_intro" model="library.book">
        <field name="name">Odoo 入门</field>
        <field name="author">小李</field>
    </record>
</odoo>

同一模块里可直接用 book_xml_intro 引用它；跨模块引用时写完整的 模块名.book_xml_intro。例如 <field name="company_id" ref="base.main_company"/> 会把一个 Many2one 字段指向已有公司。布尔值等类型可以用 eval，例如 <field name="active" eval="True"/>。不要把 ref 或 eval 当成普通文本写进标签体内。

定义列表、表单、动作和菜单

视图本身也是 ir.ui.view 记录；界面结构写在 arch 字段内。动作把模型与视图类型关联起来，菜单再指向动作。以下内容可放在 views/library_book_views.xml：

<?xml version="1.0" encoding="UTF-8"?>
<odoo>
    <record id="view_library_book_list" model="ir.ui.view">
        <field name="name">library.book.list</field>
        <field name="model">library.book</field>
        <field name="arch" type="xml">
            <list string="图书">
                <field name="name" />
                <field name="author" />
            </list>
        </field>
    </record>

    <record id="view_library_book_form" model="ir.ui.view">
        <field name="name">library.book.form</field>
        <field name="model">library.book</field>
        <field name="arch" type="xml">
            <form string="图书">
                <sheet>
                    <group>
                        <field name="name" />
                        <field name="author" />
                    </group>
                </sheet>
            </form>
        </field>
    </record>

    <record id="action_library_books" model="ir.actions.act_window">
        <field name="name">图书</field>
        <field name="res_model">library.book</field>
        <field name="view_mode">list,form</field>
    </record>

    <menuitem id="menu_library_root" name="图书馆" sequence="10" />
    <menuitem id="menu_library_books" name="图书" parent="menu_library_root"
              action="action_library_books" sequence="10" />
</odoo>

view_mode 里的类型用逗号连接，不加空格。list 是此处 Odoo 19 的列表视图名称；旧版本资料可能写 tree。菜单能否实际显示和访问还受模型访问权限影响，通常还需在 security/ir.model.access.csv 中给相应用户组配置权限。

用 XPath 继承视图

修改已有视图时，创建一条带 inherit_id 的新 ir.ui.view 记录，再在 arch 中定位目标。下面的示例继承上面定义的表单视图，在 author 字段之后加入预先定义好的 note 字段：

<record id="view_library_book_form_note" model="ir.ui.view">
    <field name="name">library.book.form.note</field>
    <field name="model">library.book</field>
    <field name="inherit_id" ref="view_library_book_form" />
    <field name="arch" type="xml">
        <xpath expr="//field[@name='author']" position="after">
            <field name="note" />
        </xpath>
    </field>
</record>

这段记录应放在原视图记录之后、</odoo> 之前。跨模块继承时，inherit_id 一般写成 原模块名.视图 XML ID，并在 manifest 的 depends 中声明该模块。常见 position 有 before、after、inside、replace 和 attributes；定位表达式必须能匹配已有视图节点。

只在安装时加载的数据

不希望模块升级时反复覆盖的初始数据，可以放在 <data noupdate="1"> 中；普通视图配置一般不应随意加这个标记，否则升级后修改可能无法按预期应用。

<odoo>
    <data noupdate="1">
        <record id="book_sample" model="library.book">
            <field name="name">初始样书</field>
        </record>
    </data>
</odoo>

QWeb 模板也是 XML

Odoo 的 QWeb 模板在 XML 元素上使用 t-* 指令控制输出。下面只演示模板语法；实际放入报告或网页时，还要按相应场景声明模板并传入 books 数据。

<t t-name="library_demo.book_list">
    <ul>
        <li t-foreach="books" t-as="book">
            <t t-out="book.name" />
        </li>
    </ul>
</t>

t-foreach 遍历集合，t-as 命名当前项，t-out 输出内容并进行 HTML 转义。QWeb 指令的具体表达式运行环境取决于模板运行在服务端还是浏览器端，不要把两种环境的对象直接混用。

参考资料

• W3C：XML 1.0 规范
• Odoo 19：模块清单
• Odoo 19：XML 数据文件
• Odoo 19：视图记录与继承
• Odoo 19：窗口动作
• Odoo 19：QWeb 模板

索引

是帮助MySQL高效获取数据的数据结构，以空间换时间

优劣 优势： 提高检索数据的效率，降低数据库的IO成本，降低CPU的消耗 劣势： 索引需要占用空间；INSERT、UPDATE、DELETE 还需维护相关索引，可能增加写入成本。

MySQL的索引在存储引擎实现的，不同引擎有不同的结构 B+树：最常见的，大部分都支持B+树索引 Hash：支持等值查找，不支持范围查找或按索引排序。MEMORY 引擎支持显式 Hash 索引，InnoDB 也可能自动构建自适应 Hash 索引。 R-树：用于空间索引；InnoDB 和 MyISAM 都支持空间索引。 全文索引：用于文本关键字检索；InnoDB 和 MyISAM 支持 FULLTEXT 索引。

索引结构

二叉树 缺点：顺序插入时会形成一个链表，查询性能会大大降低。大数据量的情况下，层级较深，检索速度慢 Hash 通过哈希函数把键映射到槽位；发生哈希冲突时，存储引擎需要进一步比较或处理冲突。

1. Hash索引仅支持对等比较（=，IN），不支持范围查询（between，>，<，。。。）
2. 无法通过索引完成排序操作
3. 等值查询通常很快，但实际性能取决于数据分布、冲突和执行计划，不能一概认为比 B+ 树快。

MySQL中的InnoDB对Hash有自适应，Hash索引是存储引擎根据B+树索引在指定条件下自动构建的

索引分类

根据存储形式划分

聚集索引选取规则：如果存在主键，主键索引就是聚集索引 如果没有主键，InnoDB 会选择所有列都为 NOT NULL 的第一个 UNIQUE 索引。 如果也没有这样的唯一索引，InnoDB 会生成隐藏的聚集索引。

由二级索引找到主键值，再到聚集索引读取行数据，称为回表查询。

索引语法

创建索引

CREATE [UNIQUE|FULLTEXT] INDEX <INDEXNAME> ON <TABLENAME>(COLUMN,COLUMN,...);

查看索引

SHOW INDEX FROM <TABLENAME>;

删除索引

DROP INDEX <INDEXNAME> ON <TABLENAME>;

SQL性能分析

SHOW STATUS 可查看服务器状态变量。下面的 Com_% 计数是服务器级别的语句计数，不限定当前数据库；也不等同于实际读取或修改的行数。

SHOW GLOBAL STATUS LIKE 'Com\_%';

慢查询日志 慢查询日志记录了所有执行时间超过指定参数（long_query_time，单位秒，默认10）的所有SQL语句的日志。默认不开启。需要在配置文件中配置：slow_query_log=1 和long_query_time=10。配置完成之后重启服务器

profile详情 可以帮助了解SQL语句时间消耗 可通过 have_profiling 查看当前 MySQL 是否支持该功能：

SELECT @@have_profiling;

SHOW PROFILE 已弃用；旧版本中可在当前会话启用，新的性能分析应优先使用 Performance Schema。

SET profiling=1;

-- 查看当前会话中各语句的耗时
SHOW profiles;

-- 查看指定 query_id 的各阶段耗时
SHOW PROFILE FOR QUERY <QUERY_ID>;

-- 查看指定 query_id 的 CPU 耗时
SHOW PROFILE CPU FOR QUERY <QUERY_ID>;

explain执行计划 EXPLAIN或者DESC命令获取MySQL任何执行SELECT语句的信息，包括SELECT语句执行过程中表如何连接和连接顺序。

-- 在 SELECT 语句前加 EXPLAIN
EXPLAIN SELECT <COLUMN> FROM <TABLENAME>;

各个字段含义

• Id
  • SELECT 的标识符；不能只凭 id 大小推断实际执行顺序。
• select_type
  • 表示select的类型，常见的取值由simple（简单表，即不使用表连接或子查询）、Primary（主查询，即外层的查询）、UNION（UNION中的第二以及以后的查询语句）、SUBQUERY（SELECT/WHERE之后包含了子查询）等
• type
  • 表访问类型，常见值有 system、const、eq_ref、ref、range、index、ALL；需结合行数和过滤条件判断性能。
• possible_keys
  • 显示可能应用在这张表上的索引，一个或多个
• key
  • 实际使用的索引。如果为NULL，就是没有使用索引
• key_len
  • 优化器选用的索引键长度，可帮助判断联合索引用了哪些列；不是越短越好。
• rows
  • MySQL认为必须要执行查询的行数，在InnoDB引擎的表中是一个估计值，可能并不总是准确的
• filtered
  • 估计经过表条件筛选后保留的行占 rows 的百分比；需结合实际执行计划判断，不能单凭数值高低评价查询。

索引的使用

最左前缀法则 联合索引通常按最左列开始使用；跳过前导列或遇到范围条件后，后续列能否用于索引查找取决于查询条件和优化器。用 EXPLAIN 确认实际使用情况。 索引列运算 对索引列直接做函数或运算，通常会妨碍普通索引用于查找；可考虑改写条件或使用函数索引，并用 EXPLAIN 验证。 字符串不加引号 字符串值应使用引号。若比较时发生隐式类型转换，可能妨碍索引使用，具体取决于列类型和执行计划。 模糊查询 LIKE 'aa%' 有机会利用 B+ 树索引做范围查找；LIKE '%aa' 通常不能使用普通 B+ 树索引定位前缀。 or连接的条件 OR 的各条件能否用索引，取决于可用索引、数据分布和优化器选择；可检查 EXPLAIN 中是否使用 Index Merge 或全表扫描。 数据分布影响 如果MySQL评估索引比全表慢，则不使用索引 SQL提示 在SQL语句中加入一些人为的提示优化操作

-- USE INDEX
SELECT * FROM <TABLENAME> USE INDEX(<INDEXNAME>) WHERE <OPTION>;

-- IGNORE INDEX
SELECT * FROM <TABLENAME> IGNORE INDEX(<INDEXNAME>) WHERE <OPTION>;

-- FORCE INDEX
SELECT * FROM <TABLENAME> FORCE INDEX(<INDEXNAME>) WHERE <OPTION>;

覆盖索引 当查询需要的列都可从索引取得时，可避免回表；按实际查询选择列，避免无必要的 SELECT *。

前缀索引 对较长的字符串列，可只索引前缀以减少索引占用；前缀过短会降低区分度，需要按数据分布选择长度。

CREATE INDEX <INDEX_NAME> ON <TABLE_NAME> (<COLUMN_NAME>(<PREFIX_LENGTH>));

可用 COUNT(DISTINCT LEFT(列名, N)) / COUNT(*) 估计前缀的区分度。区分度越高通常越利于筛选，但实际性能仍需结合索引大小和查询计划衡量。

单列索引与联合索引 单列：一个索引只包含一列 多列：一个索引包含多列 多个条件经常一起出现时，可考虑符合列顺序的联合索引；单列索引与联合索引的取舍应依据实际查询、写入成本和 EXPLAIN 结果。

索引设计原则

1. 针对数据量大、且查询比较频繁的表建立索引。
2. 对常作为查询条件、分组、排序的字段建立索引。
3. 尽量选择区分度高的列作为索引，尽量建立唯一索引，区分度越高，使用索引的效率越高。
4. 如果是字符串类型的索引，字符串长度较长，可以根据字段的特点建立前缀索引。
5. 联合索引可覆盖部分常用查询并减少回表，但不一定比单列索引节省空间。
6. 要控制索引数量，索引不是越多越好，索引越多，维护索引的代价越大，影响增删改的效率。
7. 如果索引列不能存储NULL，在建表时候用NOT NULL限制，当优化器指定每列是否包含NULL时，它可以更好得确定哪个索引最有效。

视图

视图保存查询定义，通常不单独存储结果数据；查询视图时会访问其底层表。

语法

创建或修改视图

CREATE [OR REPLACE] VIEW <VIEWNAME>(NEWCOLUMNNAME1,NEWCOLUMNNAME2,...) AS <SELECT语句> [WITH [CASCADED | LOCAL] CHECK OPTION];

查询视图

-- 查看创建视图语句
SHOW CREATE VIEW <VIEWNAME>;

-- 查询视图数据
SELECT * FROM <VIEWNAME>;

删除视图

DROP VIEW <VIEWNAME>;

视图的检查选项： 使用 WITH CHECK OPTION 创建可更新视图后，经该视图执行的 INSERT 和 UPDATE 必须使新行符合视图条件。 默认是 CASCADED。若视图 A 基于视图 B：CASCADED 会递归检查底层视图条件；LOCAL 检查 A 的条件，并继续按 B 自身的检查选项判断，不会强制给 B 添加检查选项。

视图的更新

要使得视图可以更新，视图与基表的行必须为一对一关系。如果视图包含以下任何一项，则视图无法更新：

1. distinct
2. group by
3. having
4. UNION or UNION ALL
5. 聚合函数或窗口函数

视图的作用

1. 视图可以封装常用查询，减少重复书写查询条件。
2. 可以向用户授予视图权限，并通过视图定义限制其可见的数据；权限效果还取决于视图的安全上下文和底层表权限。
3. 视图可以帮助用户屏蔽真实表结构变化带来的影响

存储过程

存储过程是保存在数据库中的 SQL 语句集合，可封装重复的数据库操作。

语法

创建

CREATE PROCEDURE 存储过程名称([参数列表])
BEGIN
    SQL语句;
END;

调用

CALL 名称(参数);

查看数据库的存储过程

SELECT * FROM INFORMATION_SCHEMA.ROUTINES
WHERE ROUTINE_SCHEMA = '数据库名称' AND ROUTINE_TYPE = 'PROCEDURE';

查看存储过程创建语句

SHOW CREATE PROCEDURE 存储过程名称;

删除存储过程

DROP PROCEDURE [IF EXISTS] 存储过程名称;

变量

在 mysql 命令行客户端中定义多语句存储程序时，需要临时更改语句结束符；DELIMITER 是客户端命令，不是 SQL。

-- 以下示例在 mysql 命令行客户端执行
DELIMITER //
CREATE PROCEDURE hello()
BEGIN
    SELECT 'hello' AS message;
END//
DELIMITER ;

系统变量

由MySQL数据库提供，不需要用户定义（全局变量GLOBAL，会话变量SESSION）

查看系统变量

SHOW [GLOBAL | SESSION] VARIABLES;

SHOW [GLOBAL | SESSION] VARIABLES LIKE '变量名模式';

SELECT @@SESSION.系统变量名;
SELECT @@GLOBAL.系统变量名;

设置系统变量

SET [SESSION | GLOBAL] 变量名=值;

SET @@SESSION.变量名=值;
SET @@GLOBAL.变量名=值;

用户变量

用户根据业务需求定义的。两个@是系统变量，一个@是用户变量，用户变量不需要提前声明类型。作用域为当前会话。 用户变量无需声明；读取尚未赋值的用户变量会得到 NULL。

赋值

SET @变量名=值,@变量名=值,...;

SELECT @变量名:=值,@变量名:=值,...;
-- SELECT设置变量，必须要要用:=，SET的话:=和=都可

使用

SELECT @变量名;

局部变量

由DECLARE声明，只能在BEGIN和END之间使用

声明

DECLARE 变量名 类型 [DEFAULT ...];

字段类型有CHAR, BIGINT, INT,VARCHAR, DATE, TIME等

赋值

SET 变量=值;
SET 变量:=值;
SELECT 字段 INTO 变量 FROM 表...;

SELECT ... INTO 应只返回一行数据；局部变量名不带 @。

IF判断

IF 条件 THEN
  ...
ELSEIF 条件2 THEN
  ...
ELSE
  ...
END IF;

参数（形参）

• IN
  • 需要调用时输入的，是默认的
• OUT
  • 作为返回值的参数
• INOUT
  • 既可以作为输入，也可以作为输出

用法

-- 使用SET对参数2进行赋值
CREATE PROCEDURE 存储过程(IN 参数1 类型, OUT 参数2 类型,...)
BEGIN
    SQL语句;
END;

CASE

语法一

CASE 变量
    WHEN 值1 THEN SQL语句;
    WHEN 值2 THEN SQL语句;
    ...
    ELSE SQL语句;
END CASE;

语法二

CASE
    WHEN 条件1 THEN SQL语句;
    WHEN 条件2 THEN SQL语句;
    ...
    ELSE SQL语句;
END CASE;

WHILE

WHILE 条件 DO
    SQL语句;
END WHILE;

REPEAT

有条件的循环，满足条件则退出。

REPEAT
    SQL语句;
UNTIL 条件
END REPEAT;

LOOP

可以实现简单的死循环，不在SQL中增加退出循环的条件。

LEAVE: 退出循环 ITERATE: 必须在循环中，表示跳过当前循环剩下的语句。

[开始标记]:LOOP
    SQL语句;
    -- 根据条件选择 LEAVE 或 ITERATE，通常不会连续执行二者
    LEAVE 开始标记;
END LOOP [结束标记];

游标

用来存储查询结果集的数据类型，可以用游标进行循环处理。游标的使用包括声明、OPEN、FETCH、CLOSE。

声明

DECLARE 游标名 CURSOR FOR 查询语句;

打开游标

OPEN 游标名;

获取游标记录

FETCH 游标名 INTO 变量1,变量2,...;

关闭游标

CLOSE 游标名;

条件处理程序

定义在流程控制执行过程中遇到条件时的处理步骤。

DECLARE handler_action HANDLER FOR condition_value,... SQL;

handler_action:

• EXIT 满足condition_value时退出
• CONTINUE 满足condition_value时继续

condition_value:

• SQLSTATE sqlstate_value:状态码，如SQLSTATE '02000'

常用的条件类别：

• SQLWARNING：SQLSTATE 类别 01。
• NOT FOUND：SQLSTATE 类别 02。
• SQLEXCEPTION：除成功、警告和未找到之外的异常类别。

存储函数

存储函数通过 RETURN 返回值；函数参数默认都是输入参数，声明时不写 IN。

CREATE FUNCTION add_one(n INT)
RETURNS INT DETERMINISTIC NO SQL
RETURN n + 1;

characteristic特性说明:

• DETERMINISTIC: 相同的输入参数总是产生相同的结果
• NO SQL：不包含SQL语句
• READS SQL DATA：包含查询数据的语句，但不包含写入数据的语句。

启用二进制日志且 log_bin_trust_function_creators=0 时，创建函数可能要求声明 DETERMINISTIC、NO SQL 或 READS SQL DATA；应按函数的实际行为声明，不能为绕过错误而标注不真实的特性。

触发器

触发器与表关联，在插入、更新或删除每行之前或之后执行，可用于数据校验或记录变更。 使用别名OLD和NEW来引用触发器中发生变化的记录内容。支持行级触发，不支持语句级触发。

1. INSERT型触发器

• NEW表示将要或者已经新增的数据

1. UPDATE型触发器

• OLD表示修改之前的数据，NEW表示将要或者已经修改后的数据

1. DELETE型触发器

• OLD表示将要或者已经删除的数据

语法

CREATE TRIGGER 触发器名
{BEFORE | AFTER} {INSERT | UPDATE | DELETE}
ON 表名 FOR EACH ROW --行级触发器
BEGIN
    SQL;
END;

查看

SHOW TRIGGERS;

删除触发器

DROP TRIGGER [数据库名.]触发器名;
--如果没有指定数据库则默认为当前数据库

参考资料

• MySQL 8.4 手册：InnoDB 聚集索引与二级索引
• MySQL 8.4 手册：空间索引优化
• MySQL 8.4 手册：EXPLAIN 输出
• MySQL 8.4 手册：SHOW PROFILE
• MySQL 8.4 手册：视图
• MySQL 8.4 手册：存储过程与函数
• MySQL 8.4 手册：触发器

覆盖的操作

• 搜索、查看、创建、评论和关闭 Issue，并调整标签。
• 查看、创建和合并 Pull Request。
• 查询 GitHub Actions 的运行记录，或触发支持 workflow_dispatch 的工作流。
• 查看、创建和修改仓库，以及读取、创建或更新仓库文件。

聊天中发送 /gh 可以查看指令树；例如 /gh issues 列出 Issue，/gh runs 查看工作流运行记录。插件还注册了 18 个大模型工具，让模型能够在对话中读取相关信息并执行已开放的操作。指令和工具使用同一套 GitHub REST API 请求层。

配置与权限

在 AstrBot 插件配置中填写 GitHub Token；可选地设置默认仓库，省去反复输入 owner/name。插件支持自定义 API 地址，可用于 GitHub Enterprise Server；也能关闭大模型工具，只保留聊天指令。

创建、修改、关闭、合并、触发工作流和写文件等操作默认仅允许 AstrBot 管理员执行。建议为 Token 只授予实际要使用的仓库和权限，并在执行写操作前核对目标对象。Token 来自插件配置，不需要写进文章或代码。

安装方式、完整指令表和所需 Token 权限见 GitHub 控制器仓库。

以下尖括号表示需要替换的名称或值，方括号表示可选部分；执行前应删除占位符。

建库

CREATE DATABASE <DATABASE_NAME>;

使用库

USE <DATABASE_NAME>;

查询当前数据库所有表

SHOW TABLES;

查询表结构

DESC <TABLE_NAME>;

查询指定表的建表语句

SHOW CREATE TABLE <TABLE_NAME>;

创建表

CREATE TABLE IF NOT EXISTS <TABLE_NAME> (
    <COLUMN_NAME> <DATA_TYPE> [NOT NULL] [DEFAULT <VALUE>] [COMMENT '注释'],
    <COLUMN_NAME> <DATA_TYPE> [NOT NULL] [DEFAULT <VALUE>]
) COMMENT = '表注释';

更新表字段(X)

-- 加列
ALTER TABLE <TABLE_NAME> ADD COLUMN <COLUMN_NAME> <DATA_TYPE> [COMMENT '注释'];
-- 改列类型
ALTER TABLE <TABLE_NAME> MODIFY COLUMN <COLUMN_NAME> <DATA_TYPE>;
-- 改列名
ALTER TABLE <TABLE_NAME> CHANGE COLUMN <OLD_NAME> <NEW_NAME> <DATA_TYPE>;
-- 删列
ALTER TABLE <TABLE_NAME> DROP COLUMN <COLUMN_NAME>;

删除表

DROP TABLE IF EXISTS <TABLE_NAME>;

删除重建表(X)

TRUNCATE TABLE <TABLE_NAME>;

重命名表(X)

RENAME TABLE <OLD_TABLE_NAME> TO <NEW_TABLE_NAME>;

删除数据库

DROP DATABASE <DATABASE_NAME>;

加索引

CREATE INDEX <INDEX_NAME> ON <TABLE_NAME>(<COLUMN_NAME>);

删索引

DROP INDEX <INDEX_NAME> ON <TABLE_NAME>;

数据类型

数值类型

1. TINYINT

   1. 大小：1 byte
   2. 有符号范围：（-128，127）
   3. 无符号范围（UNSIGNED）：（0，255）
   4. 描述：小整数值

2. SMALLINT

   1. 大小：2 bytes
   2. 有符号范围：（-32768，32767）
   3. 无符号范围（UNSIGNED）：（0，65535）
   4. 描述：大整数值

3. MEDIUMINT

   1. 大小：3 bytes
   2. 有符号范围：（-8388608，8388607）
   3. 无符号范围（UNSIGNED）：（0，16777215）
   4. 描述：大整数值

4. INT/INTEGER

   1. 大小：4 bytes
   2. 有符号范围：（-2147483648，2147483647）
   3. 无符号范围（UNSIGNED）：（0，4294967295）
   4. 描述：大整数值

5. BIGINT

   1. 大小：8 bytes
   2. 有符号范围：（-2^63，2^63-1）
   3. 无符号范围（UNSIGNED）：（0，2^64-1）
   4. 描述：极大整数值

6. FLOAT

   1. 大小：4 bytes
   2. 描述：单精度近似数，精度约 7 位十进制数字
   3. UNSIGNED 属性已弃用，需要非负值时优先使用 CHECK 约束

7. DOUBLE

   1. 大小：8 bytes
   2. 描述：双精度近似数，精度约 15 位十进制数字
   3. UNSIGNED 属性已弃用，需要非负值时优先使用 CHECK 约束

8. DECIMAL

   1. 有符号范围：依赖于M（精度）和D（标度）的值
   2. UNSIGNED 属性已弃用，需要非负值时优先使用 CHECK 约束
   3. 例子：12.3->M=3, D=1
   4. 描述：小数值（精确定点数）

字符串类型

1. CHAR
   1. 长度：0-255 个字符（实际字节数取决于字符集）
   2. 描述：定长字符串
2. VARCHAR
   1. 长度：最多 65,535 个字符；实际最大长度受字符集和行大小限制
   2. 描述：不定长字符串
3. TINYBLOB
   1. 大小：最多 255 bytes
   2. 描述：不超过 255 字节的二进制数据
4. TINYTEXT
   1. 大小：最多 255 bytes
   2. 描述：短文本数据
5. BLOB
   1. 大小：最多 65,535 bytes
   2. 描述：二进制数据
6. TEXT
   1. 大小：最多 65,535 bytes
   2. 描述：长文本数据
7. MEDIUMBLOB
   1. 大小：最多 16,777,215 bytes
   2. 描述：中等长度的二进制数据
8. MEDIUMTEXT
   1. 大小：最多 16,777,215 bytes
   2. 描述：中等长度文本数据
9. LONGBLOB
   1. 大小：最多 4,294,967,295 bytes
   2. 描述：大容量二进制数据
10. LONGTEXT
11. 大小：最多 4,294,967,295 bytes 2. 描述：极大文本数据

日期时间类型

1. DATE
   1. 大小：3
   2. 范围：1000-01-01 ~ 9999-12-31
   3. 格式：YYYY-MM-DD
   4. 描述：日期值
2. TIME
   1. 大小：3
   2. 范围：-838:59:59 ~ 838:59:59
   3. 格式：HH:MM:SS
   4. 描述：时间值或持续时间
3. YEAR
   1. 大小：1
   2. 范围：1901 ~ 2155
   3. 格式：YYYY
   4. 描述：年份值
4. DATETIME
   1. 大小：8
   2. 范围：1000-01-01 00:00:00 ~ 9999-12-31 23:59:59
   3. 格式：YYYY-MM-DD HH:MM:SS
   4. 描述：混合日期值和时间值
5. TIMESTAMP
   1. 大小：4
   2. 范围：1970-01-01 00:00:01 UTC ~ 2038-01-19 03:14:07 UTC；读写时按会话时区转换
   3. 格式：YYYY-MM-DD HH:MM:SS
   4. 描述：时间戳

DML - 数据操作

新增

INSERT INTO <TABLE_NAME> (<COLUMN_1>, <COLUMN_2>) VALUES (<VALUE_1>, <VALUE_2>);
/*
插入数据时，需要保持值与列对应；需要保证值符合列的限制；字符串和日期类型数据应该包含在引号中
*/

更新(X)

UPDATE <TABLE_NAME> SET <COLUMN_NAME> = <VALUE> WHERE <CONDITION>;

删除(X)

DELETE FROM <TABLE_NAME> WHERE <CONDITION>;

替换：主键或唯一键冲突时先删后插

REPLACE INTO <TABLE_NAME> (<COLUMN_1>, <COLUMN_2>) VALUES (<VALUE_1>, <VALUE_2>);

插入冲突时更新

INSERT INTO <TABLE_NAME> (<COLUMN_1>, <COLUMN_2>) VALUES (<VALUE_1>, <VALUE_2>) AS new
ON DUPLICATE KEY UPDATE <COLUMN_2> = new.<COLUMN_2>;

DQL - 数据查找

查询

SELECT <COLUMN_1>, <COLUMN_2> FROM <TABLE_NAME>
[WHERE <CONDITION>] [GROUP BY <COLUMN_1>] [HAVING <GROUP_CONDITION>]
[ORDER BY <COLUMN_1>] [LIMIT <OFFSET>, <PAGE_SIZE>];

设置别名

SELECT <COLUMN> [AS 别名] FROM <TABLE_NAME>;

去重

SELECT DISTINCT <COLUMN> FROM <TABLE_NAME>;

聚合函数

语法

SELECT COUNT(*) FROM <TABLE_NAME>;
-- COUNT(*) 统计所有行；COUNT(列名)、SUM、AVG 等忽略 NULL 值

-- 分组与分组后过滤
SELECT <GROUP_COLUMN>, COUNT(*) FROM <TABLE_NAME> [WHERE <CONDITION>] GROUP BY <GROUP_COLUMN> [HAVING <GROUP_CONDITION>];

-- 排序（升序asc,降序desc,默认为升序）
SELECT <COLUMN> FROM <TABLE_NAME> ORDER BY <COLUMN> [ASC | DESC];
-- 当存在多个排序条件时，当前一个字段值相同时，才会根据第二个字段进行排序

-- 分页
SELECT <COLUMN> FROM <TABLE_NAME> LIMIT <OFFSET>, <PAGE_SIZE>;
-- 起始索引一般为(查询页码-1)页x每页显示记录数量，MYSQL的方言是LIMIT，如果查询的是第一页，起始索引(0)可以省略

WHERE & HAVING的区别

• 执行时机：WHERE要先于聚合，HAVING后于聚合
• 判断条件：WHERE不能对聚合函数进行判断，HAVING可以

执行顺序

FROM
WHERE
GROUP BY
HAVING
SELECT
ORDER BY
LIMIT

DCL - 用户与权限

用户管理

查询用户

USE mysql;
SELECT User, Host FROM mysql.user;

创建用户

CREATE USER 'USERNAME'@'HOST' IDENTIFIED BY 'PASSWORD';

修改用户密码

ALTER USER 'USERNAME'@'HOST' IDENTIFIED BY 'NEWPASSWORD';

删除用户

DROP USER 'USERNAME'@'HOST';

权限管理

查询权限

SHOW GRANTS FOR 'USERNAME'@'HOST';

授予权限

GRANT <PRIVILEGE> ON <DATABASE_NAME>.<TABLE_NAME> TO 'USERNAME'@'HOST';

撤销权限

REVOKE <PRIVILEGE> ON <DATABASE_NAME>.<TABLE_NAME> FROM 'USERNAME'@'HOST';

多个权限之间可以用逗号隔开 授权时，数据库和表名可以用*代替，代表所有

内置函数

字符串

语法：SELECT FUN(参数);

数值函数

日期函数

流程函数

约束

概念：作用于表中的字段，限制表中的数据

主键约束自增：AUTO_INCREMENT

外键约束

让两个表产生联系，保证数据的一致性和完整性 拥有外键的叫子表，被参考的叫父表

父表更新、删除行为：

语法：

ALTER TABLE <CHILD_TABLE> ADD CONSTRAINT <FK_NAME>
FOREIGN KEY (<CHILD_COLUMN>) REFERENCES <PARENT_TABLE> (<PARENT_COLUMN>)
ON UPDATE CASCADE ON DELETE CASCADE;

多表关系

一对多 在多的一方建立外键，指向一的一方的主键

多对多 需要有中间表，中间表至少包含两个外键，分别关联两方主键

一对一 在任意一方加入外键，关联另一张表的主键，并且设置外键为唯一（UNIQUE）的

查询

内连接

隐式内连接

SELECT <COLUMN> FROM <TABLE1>, <TABLE2>, ... WHERE <OPTION>;

显式内连接

SELECT <COLUMN> FROM <TABLE1> INNER JOIN <TABLE2> ON <CONDITION>;

一般需要条件,否则会导致完整的笛卡儿积被查询 内连接查询的是两张表的交集部分

外连接

左外连接

SELECT <COLUMN> FROM <TABLE1> LEFT JOIN <TABLE2> ON <CONDITION>;

右外连接

SELECT <COLUMN> FROM <TABLE> RIGHT JOIN <TABLE2> ON <OPTION>;

左外连接，需要完整包含左表（第一张表）的所有记录，其查询结果为左表的所有记录加上右表中左右表的交集部分 右外连接保留右表（第二张表）的所有记录，并匹配左表中的对应记录；没有匹配时左表列为 NULL。

自连接

SELECT <COLUMN> FROM <TABLE> AS <别名> JOIN <TABLE> AS <别名> ON <OPTION>;

自连接查询可以是内连接也可以是外连接

UNION联合查询

就是把多次查询的结果合并起来，形成新的查询结果集 UNION 时表示去重合并 UNION ALL时表示不去重合并

SELECT <COLUMN> FROM <TABLE>...
UNION
SELECT <COLUMN> FROM <TABLE>...;

子查询

SQL语句中嵌套SELECT语句，称为嵌套查询/子查询

SELECT * FROM T1 WHERE COLUMN1 = (SELECT COLUMN1 FROM T2);

根据子查询结果不同，分为：

• 标量子查询（子查询结果为单个值）
  • 返回的结果是单个值（数字、字符串、日期等）。常用的操作符：= <> > >= < <=
• 列子查询（子查询结果为一列多个值）
  • 常用操作符
    • IN在指定的集合范围之内多选一
    • NOT IN不在指定的集合范围内
    • ANY任意一个满足即可
    • SOME与ANY等价
    • ALL返回列表的所有值都必须满足
• 行子查询（子查询结果为一行一个记录）
  • 常用操作符：=、<>、IN、NOT IN
• 表子查询（子查询结果为多行多列）
  • 常放在 FROM 中作为派生表；多列 IN 比较需要对应的行构造器。

根据子查询位置，分为：WHERE之后、FROM之后、SELECT之后

事务

开启事务

START TRANSACTION;
BEGIN;

提交事务

COMMIT;

回滚事务

ROLLBACK;

事务四大特性

• 原子性：事务是不可分割的最小单元，要么全部成功要么全部失败
• 一致性：事务完成时，必须要使得所有数据保持一致状态
• 隔离性：事务会在不受外部并发操作的影响下运行
• 持久性：事务一旦提交，其修改会持久保存；回滚不会保存该事务的修改

并发事务问题

• 脏读：读到了未提交的数据
• 不可重复读：一个事务先后读取同一个数据，两次读到的数据不同
• 幻读：同一事务按相同条件重复查询时，由于其他事务插入或删除了符合条件的行，结果集的行数发生变化

隔离机制

*InnoDB 的一致性读在同一事务中使用快照；锁定读和写操作还会使用锁控制并发，因此不能只用一格“是/否”概括幻读行为。

查看事务隔离级别

SELECT @@transaction_isolation;

设置事务隔离级别

SET [SESSION | GLOBAL] TRANSACTION ISOLATION LEVEL READ COMMITTED;

存储引擎

存储引擎基于表，所以存储引擎也被成为表类型

在创建表时指定存储引擎

CREATE TABLE <TABLE_NAME> (
   ...,
   ...,
   ...
) ENGINE = InnoDB [COMMENT = '表注释'];

查看当前数据库支持的引擎

SHOW ENGINES;

InnoDB

是MySQL默认的MySQL引擎 特点： DML操作遵循ACID模型，支持事务 行级锁，提高并发访问能力 支持外键FOREIGN KEY约束，保证数据的完整性和正确性

文件：xxx.ibd 启用独立表空间时，表通常对应一个 .ibd 文件，保存表数据和索引；数据字典由 MySQL 管理。 参数：innodb_file_per_table

逻辑存储结构 TableSpace：表空间，包含多个Segment Segment：段，包含多个区 Extent：区，包含多个页，大小为1M Page：页，包含多行，为数据表主力，大小为16K Row：行，包含各种字段

MyISAM

是MySQL早期默认引擎 特点： 不支持事务，不支持外键 支持表锁，不支持行锁 访问速度快

MEMORY

表数据存储在内存中。由于受到硬件问题、或者断电问题的影响，只能作为临时表或缓存使用。 特点： 内存存放 hash索引（默认） 文件： xxx.sdi：存储表结构信息

存储引擎特点

参考资料

• MySQL 8.4 手册：CREATE TABLE
• MySQL 8.4 手册：数值类型语法
• MySQL 8.4 手册：CHAR 与 VARCHAR
• MySQL 8.4 手册：日期与时间类型
• MySQL 8.4 手册：InnoDB 事务隔离级别

备份流程

插件既支持手动执行，也支持配置五段 Cron 定时运行。每轮按配置顺序处理任务，单个任务失败不会阻止其余任务；手动与定时备份共用锁，避免同一实例内的重叠执行。云端文件按日期和编号存放，编号从已有备份中确定，重启后仍能继续递增。

管理员可以通过指令启动全部或指定任务、查询历史备份、查看状态，并把选定 ZIP 下载到服务器。下载完成前会校验文件大小和 ZIP CRC；插件不会自动解压，也不会覆盖原始数据。

实现上，插件通过异步 HTTP/XML API 与 COS 通信，使用 COS v5 请求签名，不依赖腾讯云 SDK。较大的压缩包使用分块上传；压缩及批量文件读写放在工作线程中。

首次使用时，建议先备份测试目录，核对云端对象和下载后的 ZIP，再开启定时任务。运行中的数据库应先导出或停写，因为普通文件压缩不等同于数据库一致性快照。配置说明和指令列表见 COS 定时备份仓库。

提供的页面与方式

• 手机号与验证码登录。
• 添加库街区 token，以及邮箱密码登录。
• 可选的云登录与抽卡记录登录；这部分需要匹配运行环境的 cloud_api 组件。
• 抽卡记录网页查看：GsCore 上传数据后，由独立服务展示页面。

服务使用 FastAPI、Jinja2 等 Python 组件。登录链接有有效期，公开部署时建议使用 HTTPS 反向代理，并让 GsCore 只监听本机地址。PUBLIC_URL 需要与 GsCore 中配置的登录地址一致。

项目复用了 XutheringWavesUID 的登录页面、相关登录逻辑与云登录组件，并按原项目许可证使用。部署步骤、GsCore 配置示例和组件要求见 WW Login 仓库。

能做什么

• 使用管理员指令列出当前域名的解析记录，并按记录 ID 删除记录。
• 指定子域名、记录类型和记录值，新增 DNSPod 解析记录。
• 向 AstrBot 的 LLM 提供查询、新增、删除解析记录的工具；管理员可以在配置中关闭这组工具，保留指令操作。

插件通过 aiohttp 调用腾讯云 DNSPod API。它只管理插件配置中指定的域名，调用前需要填写腾讯云 API 密钥和域名。机器人指令与 LLM 工具均限制为管理员使用。

这个项目的目标是处理日常解析调整，尤其适合需要频繁为自托管服务添加子域名的场景。涉及删除记录时，先查询记录并核对 ID，再执行操作。

项目源码位于腾讯云 DNS 解析控制器仓库。

NapCat

AstrBot

早柚核心

XutheringWavesUID

RoverSign

前期准备工作

Linux/Ubuntu设备、闲置QQ号

Linux环境检查

检查与安装Git

# 检查 Git 版本
git --version

# 如果显示 "command not found"，请执行安装命令：
sudo apt update && sudo apt install git -y

检查与安装Docker(可选)

# 检查 Docker 版本
docker --version

如果没有安装Docker，需要进行安装

# 更新索引并安装Ubuntu自带的docker包
sudo apt update
sudo apt install docker.io docker-compose-v2 -y

检查环境与Github.com的网络连通性

ping github.com

如果 ping通了,延迟在100-300ms左右均属正常，可以继续。 如果显示Time out或Name or service not known：说明你的服务器无法解析或连接到 GitHub，直接clone源码大概率会失败

鸣潮机器人框架主体部署

GsCore早柚核心框架部署

:::tabs

@tab docker部署

一键部署并启动容器

docker run -d \
  --name gsuid_core \
  --restart always \
  -p 8765:8765 \
  -v /opt/gscore_data:/gsuid_core/data \
  -v /opt/gscore_plugins:/gsuid_core/gsuid_core/plugins \
  -v gsuid_core_venv:/venv \
  docker.cnb.cool/gscore-mirror/gsuid_core:latest

如果你需要自定义 docker run 命令，可以参考下表修改对应参数：

@tab docker compose部署

克隆源码并进入目录

git clone https://cnb.cool/gscore-mirror/gsuid_core.git
cd gsuid_core

启动构建

# 复制环境配置（可选）
cp .env.example .env
# 后台构建并启动
docker compose up -d --build

@tab 本地环境手动安装

检查uv安装情况

uv -V

如果没有显示版本号，则需要下载

# 使用官方脚本一键安装
curl -LsSf https://astral.sh/uv/install.sh | sh

# 立即生效环境变量 (针对当前会话)
source $HOME/.cargo/env

# 验证安装是否成功
uv -V

克隆源码并进入目录

git clone https://cnb.cool/gscore-mirror/gsuid_core.git
cd gsuid_core

安装依赖

# uv安装依赖方式
uv python install 3.13
uv sync --python 3.13
uv run python -m ensurepip

启动

# 当前目录下
uv run core

:::

安装XutheringWavesUID与配套的签到插件RoverSign

进入GsCore项目的根目录，进入gsuid_core文件夹，进入plugins文件夹

git clone https://github.com/Loping151/XutheringWavesUID.git

git clone https://github.com/Loping151/RoverSign.git

重启GsCore

配置网页控制台

开放端口号

GsCore默认运行在8765端口号，故而需要服务器配置中开放8765端口号

访问地址为：http://your-ip:8765/app

获取注册码

进入到早柚核心根目录，进入data文件夹，打开config.json文件，文件顶部在masters字段下填写你的QQ号，这是作为主人QQ

滑动到文件底部，可以看到REGISTER_CODE，复制它的值，这就是注册码，是注册网页控制台账户的唯一凭证

注册并进入网页控制台

这里可以解决99%的配置问题

在网页控制台Core核心配置中填写WebSocket Token，这是为安全性考虑

上游机器人框架部署

部署NapCat与AstrBot

:::tabs

@tab 同时部署NapCat与AstrBot

mkdir astrbot
cd astrbot
wget https://raw.githubusercontent.com/NapNeko/NapCat-Docker/main/compose/astrbot.yml
sudo docker compose -f astrbot.yml up -d

@tab 单独部署AstrBot与NapCat

点击查看如何使用Linux部署AstrBot

点击查看如何使用Linux部署NapCat

:::

配置AstrBot连接GsCore

1. 准备好在GsCore控制台填写的WebSocket Token
2. 进入AstrBot控制台，点击插件市场，搜索关键词gscore，点击安装，等待安装完成 如果没有安装成功则使用镜像地址
3. 进入AstrBot插件菜单，搜索关键词gscore，点击插件配置，填入连接Core的WsToken

验证连接情况与主人设置

在QQ中对机器人发送corestatus，如果成功返回图片，则代表当前用户为主人用户，且QQ已经正确连接到AstrBot 发送ww帮助,如果有帮助图片返回则证明插件运行成功，到此只剩下最后一步

向作者申请伤害计算token以及接入全排行token

总排行申请、反馈（仅限主人）：群号 387393347（需中转一次，因为被炸过群了）。如完全不使用QQ平台，可发邮件给客服小维 agent@loping151.com（记得写标题）申请计算服务token，要求附带具体使用平台、core信息截图和使用情况和规模说明，支持较少的请求量和用户量，但完全足以小范围使用，一般都欢迎入群。

• 为什么需要申请总排行进行使用：

  为了确保不被上传大量伪造数据影响持有率、排行等，以及 https://ngabbs.com/read.php?tid=45654606

• 总排行申请有无条件？

  待在群里，潜水不沙

• 除了总排行，插件本体功能是否有其他内容需要申请：

  无。评分功能由于是独立的服务，与插件本体无关。

控制台填写token完成后，发送ww下载全部资源

参考以及致谢

• <img src="https://xn--ntsp09fr3m.com/favicon.ico" height="70px" alt="">Echo

• <img src="https://docs.sayu-bot.com/favicon.ico" height="70px" alt="">早柚核心

• AstrBot

• <img src="https://napcat.napneko.icu/assets/newnewlogo.webp" height="70px" alt="">NapCat

Ubuntu 24.04 AstrBot v4.11.2

官方教程

http://docs.astrbot.app/deploy/platform/aiocqhttp/napcat.html

部署

如果您的网络环境在中国大陆境内，上述命令将无法正常拉取。您可能需要修改 compose.yml 文件，将其中的 image: soulter/astrbot:latest 替换为 image: m.daocloud.io/docker.io/soulter/astrbot:latest

git clone https://github.com/AstrBotDevs/AstrBot
cd AstrBot
sudo docker-compose up -d

docker-compose没安装可以用自己操作系统的包管理器安装一下 部署就这么多了喵

安装配置NapCat

NapCat部署教程

创建反向websocket客户端

URL的选择

:::tabs

@tab 与NapCat同环境

同环境意思是双方没有任何隔离 url: ws://localhost:6199/ws

@tab 同一机器但Bot在Docker

Bot记得开放对应的端口号，不然NapCat无法访问 url: ws://localhost:6199/ws 不行的话用url: ws://内网IP:6199/ws

@tab 不同服务器

url: ws://你的Bot框架所在的服务器的IP地址:6199/ws

1. Bot记得开放对应的端口号，不然NapCat无法访问
2. 如果是局域网那就用局域网IP
3. 如果是云服务器就用公网IP
4. 都不是那你还不如两个放一个服务器

:::

连接NapCat

1. 防火墙开放6185端口号
2. 访问http://公网IP:6185

记得改密码

这个的token填你在NapCat配置的token，机器人配置名字记得改，创建配置后将不允许更改

改账号密码

NapCat v4.9.70

风险

:::warning 有被嘿壳冒用NapCat的API发反动消息的风险 token必须要设置，若因使用简单密码或者默认密码导致被人破解而导致机器人被黑，后果自负 :::

1. 首先需要设密码，反正什么都设密码，嘿壳没有密码难以冒用，中招的都是没有设密码的温室花朵
2. 使用WebUI配置完成之后需要禁用6099端口号的防火墙
3. 养成良好习惯，只开要用的端口号

部署NapCat

官方网站-> NapCatQQ | 现代化的基于 NTQQ 的 Bot 协议端实现

非Docker部署方式

在Shell执行以下命令，失败就再试一次

curl -o \
napcat.sh \
https://nclatest.znin.net/NapNeko/NapCat-Installer/main/script/install.sh \
&& sudo bash napcat.sh \
--docker n \
--cli y

配置NapCat

输入<u>napcat</u>命令

需要填写作为机器人的QQ号，建议<em>使用小号</em>

开机自启动，字面意思喵

配置WebUI

:::warning 需要服务器放行6099端口号 :::

启动NapCat

:::tip 解码网站-> https://www.liantu.com/index_old.htm ::: 要是日志的二维码不能扫，就复制你的链接到解码网站生成二维码再扫

退出脚本

手机上出现Linux登录即为成功 这个号不能在电脑登录，否则会将LinuxQQ挤下线

一直点<kbd>退出</kbd>直到完全退出脚本

登录WebUI，为下一步的Bot框架配置做准备

在浏览器输入URL http://your_ipaddress:6099

:::tip 密码是你在NapCat脚本配置WebUI的时候填的Token :::

:::warning URL根据你要接入的Bot框架而定 :::

Bot框架部署教程

TRSS-Yunzai

官网-> trss.me

Yunzai在Linux部署教程

AstrBot

官网-> https://astrbot.app/

AstrBot部署教程

示例

// 发送表情包
await IMAGE(fileUrl,{isface : true})

// 发送图片
await IMAGE(fileUrl,{isface : false})

NapCat v4.9.70

:::info 前提是严格按照以下教程中关于NapCat的配置，否则需要注意端口号是否是6099 :::

Linux云崽部署教程

脚本设置方法

输入以进入脚本

napcat

来到脚本页面，进入配置Napcat，进入你的qq配置，配置HTTP服务器（正向http）

名称随意，但是不要和ws客户端重合，host改为127.0.0.1,port随意，默认也行，Token为了安全性必须写

WebUI控制台设置方法

登录NapCat控制台

:::info 打开网址 ::: :::tabs

@tab 本地运行Napcat

http://localhost:6099

@tab 云服务器运行

记得开放6099端口号 http://<你的公网ip>:6099

:::

你需要输入部署napcat时配置的密码

新建HTTP服务器

按照如图步骤点击

启动HTTP服务器

名称随便输入，打开启动，host改为localhost，输入token，点击保存

:::caution 如果不改host的情况下不加token，那我可以使用这个服务器控制你的qq，不改的话耗子尾汁 :::

这个时候你会看到页面有两个框，一个是HTTP服务器，这个是刚刚创建的，另一个是WebSocket客户端，这是部署机器人时创建的，确保两个都在开启状态

:::info 这里由于我只是本地调用，所以host设置为localhost :::

调用NapCat的API

:::info 传入的url，若是本地的napcat则是http://127.0.0.1:3000，若是其他服务器上的，则127.0.0.1改成公网ip :::

NapCat-API地址

可以看到全是post请求

可以看到在跟api文档的对比中，多了Authorization字段，这是认证必须的

import axios from 'axios'
const token = 你填写的HTTP服务器Token
 /**
     * 给指定 QQ 用户点赞
     * 
     * @async
     * @param {string} url - NapCat API 地址，例如 "http://127.0.0.1:3000"
     * @param {string|number} uid - 要点赞的 QQ 号
     * @param {number} times - 点赞次数
     * @returns {Promise<Object>} 返回 NapCat 接口响应数据
     * @throws {Error} 如果请求失败会抛出异常
     * 
     * @example
     * await NapCatAPI.thumbsUp("http://127.0.0.1:3000", 2331329306, 5);
     */
    async thumbsUp(url, uid, times) {
        try {
            const data = {
                user_id: uid,
                times: times
            };

            const response = await axios.post(`${url}/send_like`, data, {
                headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${token}` }
            });

            return response.data;
        } catch (error) {
            logger.error(`[Syuan-Plugin] 为 ${uid} 点赞失败: ${error}`);
            throw error;
        }
    },

TRSS-Yunzai v3.1.3 NapCat v4.9.70

前言

:::warning 有相当一部分插件仓库都在Github，故而确保部署环境能够以HTTP或者SSH方式访问Github :::

:::tabs

@tab HTTP方式

1. 测试连接(若无丢包则只需进行步骤1)

ping github.com

1. 若有丢包则命令行输入：

vim /etc/hosts

1. 在打开的文件中，点击键盘上的 <kbd>i</kbd>，左下角会出现-- INSERT --，将以下文本粘贴进文件中。

20.27.177.113   github.com

随后，按<kbd>ESC</kbd>，键盘输入 <kbd>:</kbd>+<kbd>w</kbd>+<kbd>q</kbd>+<kbd>Enter</kbd>

配置完成后可以到步骤1测试连接

@tab SSH方式

1. 测试连接(若成功显示Github用户名则只需进行步骤1)

ssh -T git@github.com

1. 教程配置 CSDN - Linux环境下使用SSH配置Github连接

配置完成后可以到步骤1测试连接

:::

Bot部署

Yunzai机器人的环境配置基于该脚本进行，详情可以访问官网 - Docker安装

:::warning 不要使用官网教程的自定义部分 :::

1. 在命令行输入以下命令

bash <(curl -L gitee.com/TimeRainStarSky/TRSS_AllBot/raw/main/Install-Docker.sh)

1. 进入容器内部

tsab

1. 选择TRSS-Yunzai 点击安装，等待脚本运行完成即可。

NapCat部署以及配置

NapCat部署教程

在WebUI中的反向Websocket客户端中填写

URL的选择

:::tabs

@tab 与NapCat同环境

同环境意思是双方没有任何隔离 url: ws://localhost:2536/OneBotv11

@tab 同一机器但Bot在Docker

Bot记得开放对应的端口号，不然NapCat无法访问 url: ws://localhost:2536/OneBotv11 不行的话用url: ws://内网IP:2536/OneBotv11

@tab 不同服务器

url: ws://你的Bot框架所在的服务器的IP地址:2536/OneBotv11

1. Bot记得开放对应的端口号，不然NapCat无法访问
2. 如果是局域网那就用局域网IP
3. 如果是云服务器就用公网IP
4. 都不是那你还不如两个放一个服务器

:::

安装Guoba控制台

1. 输入tsab命令进入脚本
2. 按<kbd>5</kbd>选中TRSS-Yunzai，点击确认进入
3. 按<kbd>6</kbd>选中插件管理，点击确认进入
4. 按<kbd>2</kbd>选中Git插件管理，点击确认进入
5. 按<kbd>3</kbd>选中安装插件，点击确认进入
6. 按<kbd>2</kbd>+<kbd>2</kbd>选中锅巴插件，点击确认安装

:::info 在这个界面也可以安装其他插件 :::

启动Yunzai机器人

1. 一直按<kbd><取消></kbd>，直到第一行出现打开 TRSS-Yunzai
2. 点击3次<kbd><确认></kbd>
3. 观察到日志OneBotv11(QQ) NapCat.Onebot v4.8.95 已连接表示连接成功（不一定是v4.8.95）

配置主人

1. 打开网址 :::tabs

@tab 本地运行Yunzai

http://localhost:2536/guoba

@tab 云服务器运行

记得开放2536端口号 http://<你的公网ip>:2536/guoba

:::

1. 点击获取验证码

2. 在启动Yunzai机器人步骤中打开的页面下会有显示

[16:20:35.723][MARK][  TRSSYz  ] [Guoba] 您正在请求验证码登录，若没有输出验证码，请将日志级别调整为 info 或以上
[16:20:35.723][INFO][  TRSSYz  ] ######################################################
[16:20:35.724][INFO][  TRSSYz  ] # [Guoba] 验证码登录请求                             #
[16:20:35.724][INFO][  TRSSYz  ] # 您的登录验证码为：eux1zsagp94ky810                 #
[16:20:35.724][INFO][  TRSSYz  ] # 验证码五分钟内有效且失效前不会再次打印，请尽快输入 #
[16:20:35.724][INFO][  TRSSYz  ] # 若非本人操作请忽略并考虑是否泄露了登录地址         #
[16:20:35.724][INFO][  TRSSYz  ] ######################################################

1. 输入验证码然后登录

2. 进入配置管理，进入其他

3. 新增主人账号，格式为你的机器人的QQ账号:你需要成为主人的QQ号

4. 页面往下滑到底，点击蓝色按钮<kbd>保存</kbd>

配置服务器密钥

以适配napcat反向Websocket客户端的token

1. 打开锅巴控制台下的基础配置
2. 下滑到服务器配置
3. 点击服务器鉴权并新增
4. 鉴权标识填Authorization
5. 鉴权值填Bearer，然后加个空格，然后加上你在napcat反向Websocket客户端的token
6. 点击下面的报错

至此，Linux操作系统下，TRSS-Yunzai机器人部署完成，剩下的插件需要你去挖掘，或者自己写。 附上部分插件列表 Yunzai插件索引

napcat接口调用教程

/

:::info Yunzai自从不使用icqq后就失去了戳人等移动端功能，而Napcat的函数又刚好弥补了这一点 :::

command [-option] [parameter] command: 命令本体，如目录下文件夹/文件列举，命令ls option：[可选，非必填] 命令的一些选项，用于控制命令的执行细节 parameter: [可选，非必填] 命令的参数，多用于命令的指向目标

常用Linux命令

文件与目录操作

权限与用户管理

系统管理与进程

网络相关

软件包管理

其他实用命令

tmux

创建一个名为 session-name 的新会话

tmux new -s session-name

进入已经存在的会话

tmux attach -t session-name

查看会话列表

tmux ls

终止会话

tmux kill-session -t session-name

tmux窗口命令(来源trss.me)

常见命令

Linux中一般怎么隐藏文件

文件名以.开头

如何查看CPU信息

lscpu

查看占用 CPU 使用率最高的进程

top

如何过滤文件中包括“ERROR”的行

grep "ERROR" 文件名

怎么查看某端口号

sudo netstat -tuln | grep :端口号

查看某进程号

ps aux | grep 进程名 ps -ef | grep ps_name

grep与find区别？grep用法

查看IP地址

内网IP ip addr show 公网IP curl ifconfig.me

查看家目录下的t.txt文件

cat ~/t.txt

怎么查出tomcat这个进程并杀死它

pgrep -af tomcat kill -9 pid

动态查看日志

tail -f <日志文件路径>

查看系统磁盘空间

df -h

查看当前机器监听的所有端口

ss -tuln

把一个文件夹打包成.tar.gz,以及解压拆包命令

tar -czvf archive.tar.gz folder_name

• c：创建压缩包

• z：使用 gzip 压缩

• v：显示过程

• f：指定文件名

tar -xzvf archive.tar.gz

以/etc/password的前五行内容为例，提取用户名

head -n 5 /etc/passwd | cut -d: -f1

head -n 5：取前五行 cut -d: -f1：按冒号分隔，取第一个字段（用户名）

cron后台常驻程序(daemon)用于？

cron 是 Linux 中的计划任务守护进程，用于定期执行预定的任务，如备份、自动更新、发送报告等。

哪个命令可以列出定义在以后特定时间运行一次的所有任务？

atq

bash中export命令的作用

将变量提升为环境变量，使其在当前 shell 启动的所有子进程中生效

当前目录下还有多大空间

df -h .

有个备份程序a,需要在周一到周五下午1点和晚上8点各运行一次,什么corntab可以完成这个工作

0 13,20 * * 1-5 /path/to/a

怎么从当前系统中卸载一个已经安装的文件系统

umount <挂载点路径>

哪条命令用来装载所有在/etc/fstab目录下定义的文件系统

mount -a

把f1.txt复制到f2.txt

cat f1.txt > f2.txt

快速切换到j的家目录下

cd ~j

在文件中查找以*开头的行

grep '^*' filename

ps中什么参数是显示所有用户的进程

ps -ef (e=a)

一行后面加入怎么表示未结束，下一行继续

\

命令 kill -9 的含义是

立即强制终止进程，无法被拦截或处理

对所有用户的变量设置应该放在哪个文件下

/etc/profile

linux脚本文件一般以什么开头

    #!/bin/bash

linux中提供TCP/IP包过滤功能的软件叫什么

iptables

vi中退出不保存的命令

:q!

哪个命令可以压缩部分文件

tar -czf archive.tar.gz file1 file2 dir/

对于Nginx服务器，提供子进程的缺省的用户是

www-data grep ^user /etc/nginx/nginx.conf 查看Nginx的默认用户

Nginx的主配置文件

/etc/nginx/nginx.conf

什么命令解压缩tar文件

tar -xvf archive.tar

netstat -a 命令停了很久没反应，可能是哪里的原因

可能是由于 DNS 解析慢造成的 netstat -an n跳过域名解析，直接显示IP和端口

telnet命令

用于测试 TCP 端口连通性（是否能连接到某个主机+端口） telnet ip <端口号>