宫论项目开发记录

2025年6月11日
1、对xc_cos_cdn_refresh_hook进行了优化处理。首先，通过curl发起请求并将返回结果存储在response变量中。接着，使用json_decode函数将返回的内容转换为数组结构。随后，通过isset函数检测$json['Response']['RequestId']是否存在。如果该变量存在，则表示缓存刷新成功；如果不存在，则意味着刷新失败，此时直接返回code=1，并提供错误提示内容：“CDN缓存清除失败: 未知错误”。
2、新增了一个名为xc_cos_cdn_thaw_hook的钩子，专门用于解封那些已经被封禁的CDN文件。之前，一旦对象存储文件通过xc_cos_cdn_ban_hook进行了封禁处理，该文件便会被永久禁用，无法通过外网（CDN节点）进行访问。如果不及时进行解封，文件将永远无法恢复使用。因此，新增的这个HOOK旨在解决这一问题，确保在文件被误判为违规后，能够及时解除限制。该方法需要传递一个固定变量url_cdn，该变量代表对应的CDN加速资源的访问路径。此举不仅提高了系统的灵活性和容错能力，也确保了文件资源的正常流通和使用。
3、xc_cos_cdn_thaw_hook函数采用标准的数组结构进行返回，确保上级系统可以直接接管并识别处理响应结果。返回的固定值有两个：code用于表示执行处理的状态。如果返回值为1，则表示解封失败，接口返回了错误。此错误可能因多种原因引起，例如权限不足、接口异常、参数错误、文件不存在等。具体的失败原因需要通过第二个变量msg来获取。如果返回code=0，则表示解封成功。注：不管什么样的返回结果，都需要返回code+msg这两个参数。
4、在初始化过程中，xc_cos_cdn_thaw_hook文件资源解封方法通过调用xc_get_option函数，读取后台设置的相关【腾讯云参数信息】，其中包括【xc_tencent_secret_id、xc_tencent_secret_key、xc_upload_cos_region、xc_upload_cos_bucket、xc_upload_cos_domain】等重要配置。这些参数分别代表腾讯云账户的身份识别ID、访问请求的密钥、对象存储桶所在的地域、存储桶的名称以及用于CDN加速的域名。通过对这些参数的统一封装，后续的API接口在执行解封动作时，能够顺利对文件进行相关操作和处理，确保资源的正常访问和流畅的用户体验。
5、在执行xc_cos_cdn_thaw_hook的解封操作时，采用API接口而不是集成SDK的方法来发起请求。具体流程如下：首先，我们需要初始化腾讯云后台的相关账户参数，以便生成签名。这个过程中，会获取当前的时间戳和随机参数，并通过base64编码和hash_hmac方法进行签名处理，从而获得授权令牌。接下来，向腾讯云CDN的相关API接口发送请求，并提交生成的签名和需要解封的域名。在收到接口返回的结果后，根据具体响应执行相应的业务逻辑处理。需要注意的是，签名所需的所有参数均通过后台进行配置和处理。
6、为了确保解封请求能够得到正常的响应处理，与腾讯云CDN接口进行API交互时，采用了curl方式进行处理。具体步骤包括：首先，通过签名机制封装好GET链接【cos_cdn】；然后，使用curl_init函数构建请求，并将返回结果存储在response变量中。为确保请求的有效性，通过curl_errno函数来检测是否存在错误，并在出现错误时返回一个包含code和msg的数组结构。接下来，判断返回结果是否为JSON格式，如果是，则使用json_decode函数将其转换为数组，并将结果赋值给json变量。最后，通过curl_close函数关闭CURL请求，以释放资源。这样一套流程确保了请求的准确性和响应的有效处理。
7、在xc_cos_cdn_thaw_hook的开发中，引入了try-catch机制，从签名封装到curl返回结果的处理，整个流程都在try块中进行。如果在此过程中发生任何错误，catch块会捕获异常并处理，确保程序的稳健性。当catch捕获到异常时，系统会立即返回一个结构化的响应，其中包含code=1和msg='异常错误: ' . $e->getMessage()。这种设计不仅可以确保任何解封钩子过程中发生的错误都能被有效追踪，还能让上层系统通过判断返回的code来快速确定解封处理是否成功完成，极大地提高了故障诊断和修复的效率。
8、为了确保接口的稳定性，在使用 xc_cos_cdn_thaw_hook 进行 CDN 资源解封时，我们增加了日志监听来处理错误情况。日志的唯一标识为 cos_cdn_thaw_error，并通过 xc_log_error_warn 方法写入日志系统。日志格式为：[时间：' . date("Y-m-d H:i:s") . '] - [解封资源：' . $url . '] - [错误：' . $e->getMessage() . ']。当系统通过 catch 捕获到异常错误时，会立即触发日志写入，以详细记录此次解封失败的具体原因。值得注意的是，该日志仅用于记录错误，不会触发报警机制，旨在为运维人员提供便捷的故障排查依据。
9、在成功调用xc_cos_cdn_thaw_hook接口解封CDN资源文件（接口返回成功，code=0）后，将立即触发xc_cos_cdn_refresh_hook方法，以确保所有CDN节点刷新该文件的缓存状态。这一操作至关重要，因为它能够保证解封后的文件实时同步至所有节点，使用户能够及时访问最新的资源。如果不执行刷新动作，已解封的资源可能由于缓存机制的影响，仍需等待数小时才能正常访问。因此，在完成解封后，及时刷新CDN节点是确保用户体验的关键步骤。
10、xc_cos_cdn_thaw_hook完成封装处理，整个执行流程如下：1、创建一个 $result 数组，用于存储操作结果。默认情况下，code 为 1（表示失败），msg 为“初始化失败”。2、使用 try-catch 块来捕获和处理任何可能发生的异常。3、通过 xc_get_option 函数获取必要的配置信息，包括 secretId、secretKey、region、bucket 和 cos_domain。这些信息用于生成请求签名和构建 API 请求。4、生成请求参数：构建请求字符串 $signStr，包含请求方法、API 版本、操作类型（EnableCaches）等信息。使用 hash_hmac 和 base64_encode 生成请求签名 $signature。5、使用 cURL 初始化请求，设置请求 URL 为 $cos_cdn，执行 cURL 请求，并将结果存储在 $response 中。6、使用 curl_errno 检查 cURL 请求是否出现错误。如果有错误，抛出异常并记录错误信息。7、使用 json_decode 将 $response 转换为关联数组 $json。检查 $json 中是否包含 SuccessUrls，以确定请求是否成功。8、如果请求成功（存在 SuccessUrls），调用 xc_cos_cdn_refresh_hook 函数刷新缓存。9、如果在请求或处理过程中抛出异常，进入 catch 块。记录错误日志，包括时间、URL 和错误信息，调用 xc_log_error_warn 记录日志。
11、针对腾讯云【COS】对象存储的文件处理方法，所有相关的钩子函数已全面封装，确保文件管理更加高效和安全。具体包括以下几个方面：1、xc_delete_cos_file_hook：这是一个对象存储文件删除钩子，所有的文件删除操作必须通过这个方法进行，以确保操作的规范性和安全性。2、xc_cos_cdn_ban_hook：用于封禁CDN资源的方法。当对象存储中的文件被删除后，必须立即通过此方法封禁相应的CDN文件，以防止节点缓存中仍然存在被删除的文件。3、xc_cos_cdn_refresh_hook：此方法用于刷新CDN资源的缓存请求，通知所有CDN节点对文件进行更新处理，从而清除旧的缓存内容，确保用户访问的是最新的文件。4、xc_cos_cdn_thaw_hook：用于解封CDN资源的方法。在出现误删、误封或误判的情况下，可以通过这个方法解除对CDN节点的封禁状态，恢复文件的正常访问。这些钩子函数的封装，极大地提高了对象存储文件的管理效率，保障了数据的安全性和一致性。

2025年6月10日
1、新增了一个名为xc_cos_cdn_ban_hook的方法，该钩子专门用于处理CDN域名的封禁。使用时需要传递一个固定变量（cdn_url，即对应的CDN域名加速地址路径）。在COS对象存储文件被删除的情况下，该钩子会对相关的CDN文件进行封禁，防止用户继续通过各地的分发缓存访问这些文件。如果仅仅删除对象存储文件而不处理CDN文件，会导致在CDN缓存未过期之前，用户仍然能够访问这些内容，这对于涉及违规的图片和视频资源而言，可能带来巨大的潜在风险。因此，通过该钩子实现及时的CDN封禁是非常必要的，以确保违规内容不会继续传播。
2、在通过内置钩子发起CDN资源封禁请求时，为了确保返回结果能够被上级系统直接接收并处理，xc_cos_cdn_ban_hook无论封禁操作是否成功，都会返回一个标准化的数组结构。其中，code字段用于表示执行状态：固定值1表示执行失败，即封禁未生效。失败的原因可能包括网络异常、接口错误、权限不足、SDK错误、参数异常等多种情况。具体的失败原因需要通过msg字段来获取。如果code为0，则表示执行成功，资源封禁已成功生效，通常情况下，该文件将无法从外网访问。
3、在xc_cos_cdn_ban_hook的初始化阶段，系统通过调用xc_get_option函数来动态读取后台配置的相关信息，包括【xc_tencent_secret_id、xc_tencent_secret_key、xc_upload_cos_region、xc_upload_cos_bucket、xc_upload_cos_domain】等参数。这些参数分别对应腾讯云账户的ID、请求的密钥、存储桶的地域、存储桶的名称以及CDN加速域名。通过统一封装这些参数，系统确保在处理与COS相关的任务时能够灵活地适应任何配置的变化，避免因参数硬编码而导致的业务异常。这种设计不仅提高了系统的灵活性和稳定性，还确保了在配置变更时能迅速响应并调整，维护业务的连续性和可靠性。
4、在完成初始化参数的封装之后，系统会开始构建API接口请求，其中包含了封禁资源所需的所有参数。为了确保数据的完整性和安全性，我们使用base64_encode和hash_hmac对参数进行签名处理。接着，通过API接口发起GET请求，将签名和需要封禁的CDN域名以GET参数的形式传递给腾讯云接口，进而请求对指定资源进行实时封禁。收到响应后，我们会对返回的结果进行判断处理：如果响应结果中包含【Response】，则表示封禁操作成功，此时返回code=0；如果响应结果中未包含【Response】，则说明处理失败，返回code=1。
5、在xc_cos_cdn_ban_hook发起借款请求时，使用curl库来处理请求。具体的参数配置如下：通过curl_setopt函数将请求的接口设置为cos_cdn，采用GET方式传递参数，并且设置请求的响应时间为5秒，以避免长时间等待导致进程阻塞。如果请求时间超过5秒，系统将自动断开连接。请求的结果会被存储到变量response中，然后通过curl_errno函数检查是否发生错误异常。如果检测到错误，程序将立即终止并返回相应的错误信息；如果没有异常，则返回处理后的结果。最后，通过curl_close函数关闭此次curl请求，确保资源的有效释放。
6、在封禁CDN资源时，为确保接口能够正常响应并避免由于错误导致无法识别的问题，采用了try-catch机制来捕获可能出现的异常。在所有请求的执行过程中，首先通过try块进行响应处理。如果在请求过程中发生错误，例如网络超时、接口异常或参数错误等情况，catch块将捕获这些异常，并输出详细的错误信息（异常错误: ' . $e->getMessage()）。这种处理方式不仅可以有效地识别和记录错误，还能及时终止后续的处理流程，并返回一个状态码code=1，确保系统的稳定性和可维护性。
7、通过内置方法发起封禁CDN资源的时候，如果发生异常错误将会触发日志写入功能，日志的标识为：cos_cdn_ban_error，日志的格式为：[时间：' . date("Y-m-d H:i:s") . '] - [封禁资源：' . $cdn_url . '] - [错误：' . $e->getMessage() . ']。日志将通过xc_log_error_warn方法进行写入，旨在详细记录执行失败的原因。这一过程仅涉及日志记录，不会触发报警机制，旨在为后续问题排查提供详尽的信息支持。
8、在处理CDN资源封禁请求后，通常需要等待一段时间才能实现全网生效。然而，在某些情况下，可能需要即时生效，这时可以通过API接口发起一个刷新请求，将资源的封禁状态立即同步至所有节点服务器。考虑到许多场景都需要使用这一刷新动作（如封禁资源、删除资源、解封资源等），我们已将其封装成一个hook钩子，以便在需要时直接调用。这个钩子被命名为xc_cos_cdn_refresh_hook，使用时需要传递一个固定变量【cdn_url】，即需要刷新的CDN请求地址。通过这种机制，我们能够确保资源状态在全网快速同步，提高响应效率和操作便捷性。
9、在处理xc_cos_cdn_refresh_hook的流程中，与封禁方法有着相似的步骤，区别仅在于所请求的接口不同。首先，需要初始化腾讯云的参数和秘钥，确保在后续步骤中能够正确进行身份验证。接下来，利用账户参数进行签名处理，这一步是为了保证请求的安全性和有效性。随后，通过构建加密签名来确保请求的完整性和不可篡改性。完成这些准备工作后，发起curl请求以触发CDN的即时刷新操作，目的在于清空指定资源的缓存，以便全网节点能够实时响应和处理最新的数据。处理结果的反馈是通过标准数组结构返回，其中code=0表示刷新成功，而code=1则意味着刷新失败。这种结果反馈机制使得我们能够快速判断操作的成功与否，并采取相应的后续措施。
10、xc_cos_cdn_refresh_hook发生错误异常，同样至此try-catch来处理。并且会将对应的错误通过xc_log_error_warn写入到日志文件【cos_cdn_refresh_error】中，对应的日志格式为：[时间：' . date("Y-m-d H:i:s") . '] - [刷新资源：' . $cdn_url . '] - [错误：' . $e->getMessage() . ']，该日志同样不会触发报警，只是记录错误，方便后续的问题追踪处理。运维可以通过定期检查日志，来确保接口的正常运作。
11、当通过 xc_cos_cdn_ban_hook 发起资源封禁请求时，如果接口响应指示处理成功，在返回数组结构之前，会通过 xc_cos_cdn_refresh_hook 刷新当前资源的CDN节点缓存。这一过程确保资源在封禁后立即无法访问。同时需注意，在调用CDN封禁方法时，必须验证当前环境是否处于异步状态。如果环境不是异步的，则需要强制使用Swoole进行处理，因为涉及到第三方接口的调用，若采用同步执行方式，将会严重阻塞当前进程，从而影响用户体验。因此，确保异步处理不仅提高了效率，还能保证系统在高负载情况下的稳定性。

2025年6月9日
1、xc_upload_hook_success文件上传成功回调钩子会在文件成功同步后触发，随后通过xc_upload_video_config读取对应的上传场景配置。若检测到当前场景的【$config['delete'】选项已开启，则表明该场景要求对本地文件进行删除处理。此时，系统将调用xc_delete_local_file_hook执行删除操作，以清理本地服务器上的文件。需要注意的是，在通常情况下，若未采用云服务器机制，不建议开启本地文件删除功能，以避免潜在的数据丢失或无法恢复的问题。
2、新增 xc_delete_cos_file_hook 钩子，用于处理对象存储桶文件删除的相关任务。该钩子将严格按照宫论 HOOK 的标准要求进行设计与实现，涵盖拦截、业务逻辑执行以及回调操作等完整流程，确保其功能稳定且具备高度的可扩展性。在设计过程中，特别注重向上兼容性，确保后续的系统更新能够在无需修改源代码的前提下正常支持该钩子。此外，该钩子不仅负责本地文件删除的处理，还需要支持远程文件删除操作，从而使系统在清理过期文件时能够正确响应并发起删除任务，有效提升文件清理的全面性和效率。
3、xc_delete_cos_file_hook采用标准的数组结构进行返回设计，以确保后续执行流程能够直接接收并处理响应结果，同时将结果返回至上一级调用。返回的数组包含两个必要参数：第一个参数是code，用于标识处理结果状态。如果code为0，则表示当前操作已成功删除指定的COS对象存储桶文件；如果code为1，则表明删除任务失败。失败的原因可能涉及多种情况，例如权限不足、文件不存在、SDK错误或网络异常等问题。具体的错误原因会通过第二个参数msg进行详细说明，便于开发人员快速定位问题并进行针对性处理。
4、在通过HOOK发起COS文件删除任务时，系统会首先进入初始化状态，具体处理流程如下：首先，利用require_once加载xc_sdk_composer，以确保当前运行环境能够成功引入相关的Composer包，从而加载对应的SDK文件，确保功能正常调用。随后，系统会读取后台配置参数，包括xc_tencent_secret_id、xc_tencent_secret_key、xc_upload_cos_region、xc_upload_cos_bucket以及xc_upload_cos_domain等关键信息。这些参数分别对应腾讯云账户的密钥信息、对象存储桶的地域配置、自定义域名等重要内容，旨在全面获取对象存储服务所需的环境配置。接下来，这些参数会被封装处理，以构建符合需求的COS任务请求，从而为后续的文件删除操作提供完整、可靠的基础支持。
5、完成COS参数的初始化处理后，通过调用new Qcloud\Cos\Client构建cosClient对象，该对象需要依赖之前封装的参数来实现COS删除操作所需的签名鉴权。如果cosClient对象生成失败，系统将直接返回code=1，并附带详细的错误信息，提示用户操作权限不足或配置异常；若生成cosClient对象成功，则后续将通过该对象发起deleteObject请求，完成指定文件的删除操作。需要注意的是，COS对象存储的相关参数均统一调用后台配置，禁止直接硬编码，以确保系统的灵活性与安全性。
6、一旦成功构建cosClient对象，接下来会通过deleteObject方法发起删除指令。该方法所需的参数包括两个：其一是bucket，即对象存储桶的标识符，这通常由上级逻辑继承而来；其二是Key，即需要删除的文件路径地址。为确保删除操作的准确性，Key参数在被传递时会经过str_replace处理，主要是移除xc_upload_cos_domain对象存储CDN自定义域名的部分，以避免因路径错误导致删除失败。删除请求发出后，系统会将处理结果赋值给result变量，用于后续逻辑判断和操作。
7、通过 xc_delete_cos_file_hook 方法发起 COS 对象文件删除请求。由于该操作涉及远程请求处理、SDK 签名生成等复杂流程，为了保证返回结果的合理性与稳定性，方法内部采用了 try-catch 异常捕获机制，对潜在的错误进行监听与处理。这样可以有效避免因不可控错误导致的异常返回情况，从而确保执行过程的安全性和可靠性。需要特别注意的是，无论执行是否成功，整个过程必须返回标准的数组格式。如果在 catch 中捕获到错误，则会返回一个包含错误信息的数组，其中 code 的值为 1，msg 为捕获到的异常信息 $e->getMessage()，以便后续能够快速定位问题并作出处理。
8、在执行 COS 文件删除的过程中，当 try-catch 捕获到删除失败的异常时，系统不仅会终止当前的删除操作，还会将失败的具体原因记录下来，方便后续追踪和处理。错误信息将通过 xc_log_error_warn 方法写入日志，日志内容包括时间、文件地址及错误详情，格式如下：[时间：' . date("Y-m-d H:i:s") . '] - [地址：' . $file . '] - [错误：' . $e->getMessage() . ']。写入的日志文件标识为 cos_delete_error。需要注意的是，该日志仅用于记录异常信息，并不会触发报警机制，因此后续处理需要依赖日志内容进行人工或自动化分析。
9、cos删除请求发起后，会将结果赋值到result，并对result['Location']字段进行验证。如果该字段不为空，则表示删除操作已成功，此时系统会返回code=0，并附加一个link字段，link字段表示被删除文件的具体地址；如果$result['Location']为空，则认为删除失败，此时系统将返回code=1，并附带msg提示“COS文件删除失败”。需要注意的是，验证过程是通过empty函数来判断Location字段是否为空，即使删除过程中发生错误，也不会触发日志写入动作，后续处理仍会按照既定逻辑继续执行。
10、由于文件删除涉及的场景较为复杂且多样化，包括本地删除请求（local）、腾讯云对象存储删除（cos）、远程FTP文件删除（ftp）以及远程SFTP协议文件删除（sftp）。在这些删除场景中，每次完成文件删除操作后，都需要执行相应的回调操作。为此，新增了一个钩子函数：xc_delete_success_hook。该钩子在触发时需传递两个变量：type 和 file。其中，type 用于标识删除的具体场景，帮助确定删除的来源；file 则表示文件的具体地址，可能是文件的 key 值，也可能是完整的 URL 地址。这一设计旨在更好地支持多场景下的删除操作，同时确保后续回调逻辑的灵活性与统一性。
11、xc_delete_cos_file_hook完成封装处理，使用 require_once 加载 xc_sdk_composer，确保运行环境能够成功引入腾讯云 SDK 的相关文件。读取后台配置参数，将这些参数封装为一个配置集合，为后续的 COS 删除操作提供支持。用 new Qcloud\Cos\Client 构建 cosClient 对象。使用 cosClient 对象调用 deleteObject 方法发起删除指令。验证 result['Location'] 字段：如果字段不为空，表示删除成功：如果字段为空，表示删除失败。使用 try-catch 机制对删除操作进行监听：如果捕获到异常，返回 code=1 和 msg，其中 msg 包含捕获到的异常信息 $e->getMessage()。过 xc_log_error_warn 方法将错误信息写入日志文件 cos_delete_error：日志内容包括时间、文件地址及错误详情。删除操作完成后，触发 xc_delete_success_hook 钩子函数。注：完整地处理了 COS 对象文件的删除任务，同时保证了异常捕获、日志记录以及回调操作的执行。

2025年6月6日
1、xc_upload_hook_success功能新增了一个验证参数保护机制：系统在处理文件上传场景时，会通过xc_upload_video_config方法读取当前的上传场景配置，并将其存储到变量config中。如果config存在且为数组类型，系统将进一步检查场景配置中是否启用了本地临时文件删除功能（即$config['delete']参数）。若该功能被开启，系统将执行额外的逻辑操作，通过内置方法发起文件删除请求，确保本地临时文件被及时清理同步删除，从而提升资源管理效率，同时避免临时文件堆积可能带来的存储压力或安全风险。这一改进优化了上传流程的安全性与稳定性，为后续文件管理提供了更可靠的保障。
2、新增一个HOOK钩子：xc_delete_file_hook，用于处理本地服务器上的文件删除操作。该钩子要求传递一个固定变量file，该变量代表需要删除的文件的绝对路径地址。为了确保删除操作的安全性和可靠性，钩子在执行过程中会进行严格的安全校验，防止误操作或恶意请求。值得注意的是，后续凡是涉及本地服务器文件的清理工作（如日志管理机制中的文件清理），均需通过此HOOK发起并执行，以实现统一管理和规范化操作。
3、xc_delete_file_hook本地文件删除钩子在操作完成后，会统一返回标准化的数组结构，以便上层逻辑能够直接接收并处理结果。返回内容包含两个固定字段：【code】表示处理状态结果，值为0时表明文件删除成功；值为1则表示删除失败，失败原因可能包括文件不存在、权限不足等多种情况。【msg】用于承载失败时的具体原因信息，方便后续排查问题。如果删除失败，开发者可以通过该字段详细了解失败的具体原因并进行针对性处理，从而提升系统的稳定性与可靠性。
4、在使用 xc_delete_file_hook 删除文件的过程中，首先会对传入的 file 变量进行检查。如果该变量为空，或者通过 file_exists 函数确认文件不存在，则会立即返回相应的错误信息，并终止后续操作。若文件确实存在，则系统会调用 unlink 方法发起删除请求，并根据删除结果进行处理。若删除成功，将返回 code=0 和 msg=文件删除成功的提示；若删除失败，则返回 code=1 和 msg=文件删除失败的错误信息。整个过程逻辑清晰，能够有效避免因参数异常或文件不存在引发的操作错误，同时对删除操作的结果给予明确反馈。
5、file变量的功能经过优化升级，现在不仅支持本地文件路径作为参数传递，还新增了通过xc_upload数据表中的ID主键进行传参的能力。这一改进非常重要，因为在实际操作中，文件的删除请求往往是通过媒体库进行查找和管理的，因此支持ID主键方式删除本地文件显得尤为必要。具体处理流程如下：首先，系统会通过is_numeric函数验证传入的file参数是否为数字类型。如果验证通过，表示参数为ID主键，此时将通过xc_query_upload函数从数据库中提取对应的文件信息；若提取失败，则直接返回相应的错误提示信息。若提取成功，则从提取结果中获取$upload['local']字段的值，并将其保存到local_file变量中，用于后续处理。这一优化显著提升了文件操作的灵活性和便捷性，为系统的文件管理提供了更高效的解决方案。
6、在部分删除场景中，删除请求可能直接通过图片或视频文件的外网URL地址发起。因此，需要将远程文件地址转换为本地绝对路径以便进一步处理。这一过程依赖于方法 xc_is_upload 的解析功能。该方法会解析当前提供的 URL 参数，并判断文件是否存在于数据库表中：若存在，则返回与该文件相关的记录数组，包括缓存信息；若不存在，则返回 false。如果成功匹配到相应的数组结构参数，则直接提取数组中的 upload['local'] 字段值，以获取文件的本地绝对路径，从而完成删除请求的后续操作。
7、xc_delete_file_hook目前已支持三种文件删除处理。分别为：直接传递本地绝对路径，发起删除请求。传递媒体库的ID主键，通过统一查询，获取到本地文件路径，发起删除。检测文件是否包含域名，如果包含域名信息，则通过xc_is_upload进行解析处理，如果匹配成功则返回 upload['local']并发起对应的删除请求。如果上述三点都匹配失败，则返回对应错误。注：无论哪种处理，都需要最终将文件转为服务器绝对路径，并通过unlink发起删除。
8、为了提升文件删除操作的安全性和可靠性，xc_delete_file_hook现已通过try-catch机制对unlink($file)可能产生的异常进行处理，确保错误能够被准确捕获和妥善处理。具体执行流程如下：首先，在删除文件之前会检查目标文件是否存在。如果文件不存在，则立即抛出异常以提示问题。若文件存在但删除操作失败（如因权限不足等原因），同样会抛出异常。所有捕获到的异常均会输出详细的错误信息，同时触发后续的错误处理逻辑。需要注意的是，无论错误类型如何，所有异常均统一返回code=1，以便后续处理能够保持一致性。
9、通过xc_delete_file_hook成功执行本地文件删除后，会将该删除操作详细记录到日志中，以确保操作具有可追溯性和审计功能。日志内容包括删除时间、被删除文件的路径以及执行删除操作的用户信息，格式如下：[删除时间 - ' . date("Y-m-d H:i:s") . '] [删除文件 - ' . $local_file . '] [删除人 - ' . xc_is_login() . ']。日志的写入是通过xc_log_error_warn完成的，并为该类日志设置了唯一标识：delete_local_file。需要注意的是，此类日志仅用于记录删除动作，不会触发任何报警机制，旨在为后续的操作追踪和问题排查提供可靠的数据支持。
10、本地文件删除成功后，将触发一个名为【delete_local_file】的Redis计数器进行统计处理，统计操作通过xc_redis_count完成，用于记录本地文件删除的数量。后续可以通过get_redis_count($key)方法获取详细的统计数据。该功能支持多维度查询统计，包括总数、今日、昨日、本周、上周、本月、上月、今年及去年等时间维度，能够全面呈现不同时间段内本地文件的删除情况，为后续分析和管理提供了便捷的数据支持。
11、xc_delete_local_file_hook完成封装处理，这是一个用于删除本地文件的钩子函数，功能全面且灵活。它支持通过文件ID、完整URL地址或本地文件路径进行文件删除操作，适应不同场景需求。删除过程中，如果文件不存在或操作失败，系统会返回详细的错误信息，帮助快速定位问题；若删除成功，则会自动记录操作日志，同时更新Redis中的删除计数，确保数据的实时性和准确性。该函数的核心参数$file可接受文件ID、完整URL地址或本地文件路径作为标识，进一步提升了操作的便捷性和适配性。最终返回的删除结果为一个数组，包含状态码和相关消息，清晰地传递操作结果，便于后续处理和数据追踪。

2025年6月5日
1、完成xc_upload_hook上传事件的全面重构与优化，新版本集成了多项关键功能，包括【befor：事件拦截、afte：事件回调、log：日志记录、redis：计数器统计】等特性，进一步提升了模块的灵活性与可扩展性。同时，新增支持swoole异步处理方案，大幅提高整体执行效率。重构后的上传钩子兼容多种同步方式，涵盖本地服务器同步上传、远程FTP、SFTP服务器同步处理以及COS对象存储桶方案，并且开放了其他上传方式的一键接入功能，为复杂场景下的文件上传需求提供了高效便捷的解决方案。
2、针对xc_upload_hook_success方法进行了优化与重构，该方法主要在文件远程同步成功后主动触发，用于执行一系列关键的业务逻辑处理，包括计数器管理、缓存清理以及日志更新等。由于涉及的处理动作较多，为提升性能与系统响应效率，本次重构重点在于引入swoole异步处理机制。重构后，系统在触发该方法时会通过is检测当前运行环境是否处于异步进程状态。如果检测到不处于异步环境，系统将通过内置方法将当前执行请求转发至swoole服务器进行异步响应处理，确保任务的高效执行与资源的合理分配。这一改进不仅优化了方法的执行效率，同时为后续扩展提供了更强的灵活性和兼容性。
3、xc_query_upload全面移除【xc_upload_hook_afte】动作回调通知事件，将其功能迁移至【xc_upload_hook_success】中进行触发响应。这一调整的主要原因在于，无论上传类型为何，系统都会主动触发【hook_success】，因此将第三方事件回调统一迁移到此处进行处理显得更为合理。一方面，该方法原生支持Swoole，能够更好地适配高并发场景；另一方面，实现了事件处理逻辑的统一，减少了冗余操作。未来接入新的上传接口时，也无需额外调整【hook_afte】，进一步提升了系统的扩展性与维护效率。这一优化不仅简化了代码逻辑，还为后续开发提供了更高的灵活性与稳定性保障。
4、在xc_upload_hook_success初始化之前，系统会通过xc_query_upload方法查询上传记录并将结果进行缓存处理。查询操作默认优先从缓存中读取数据，若缓存中存在有效结果，则直接使用缓存内容，从而显著减少数据库的SQL请求压力，提升性能。如果xc_query_upload成功获取到对应的上传记录，系统会将查询结果存储到upload数组中，后续的所有处理逻辑都将基于该数组进行操作。值得注意的是，旧版本中曾使用xc_get_sql方法直接读取数据，但该方法已被弃用，现阶段统一采用xc_query_upload进行标准化查询，以确保数据操作的规范性与一致性。
5、xc_upload_hook_success现已统一返回标准化的数组结构。尽管在大多数场景下返回结果不会被进一步处理，但为了确保接口响应的规范性，仍然采用数组结构进行处理。返回结果中，code字段用于标识处理状态：当code=0时，表示所有处理流程已成功完成；当code=1时，则表明处理失败，可能是在执行过程中出现了意外情况。对于失败的具体原因，可通过msg字段进行追溯。常见的错误包括xc_query_upload读取失败或异步操作异常等问题。这种标准化的响应方式不仅提升了接口的可读性，也为后续的错误定位和问题排查提供了便利。
6、在上传回调接口中，新增了一个有序集合的统计处理功能。首先，系统通过 $upload['user_id'] 获取当前文件的上传用户，并将其赋值给 user_id。接着，使用 xc_day_time 获取当天的时间戳，将其作为集合的成员。然后，通过调用 update_redis_sorted_set 方法，对有序集合进行统计处理，以 upload_size 作为记录标识，记录每天的文件上传总大小。当前文件的大小在创建 xc_upload 数据表时，已经被写入 size 字段，此处只需通过 $upload['size'] 读取即可。该有序集合的统计功能能够有效统计每日文件上传的数量和总大小，为后续的数据分析提供了基础。
7、在文件通过 hook_success 完成上传回调后，为了更精准地统计宫论平台附件的整体状态，会根据 $upload['format'] 文件类型触发对应计数器的处理逻辑。系统会针对不同文件类型（例如图片=image、视频=video、声音=voice）记录上传成功的次数，并以 'upload_' . $upload['format'] 的形式作为标识存储相关数据。通过 get_redis_count($key) 函数，可以灵活获取详细的统计信息，支持多维度的数据分析，涵盖总数统计以及时间维度的查询，包括今日、昨日、本周、上周、本月、上月、今年和去年等不同时间范围的数据。
8、升级优化xc_redis_count：宫论计数器的处理方法。该方法主要用于在Redis中实现计数操作，功能设计较为复杂。首先，它通过事务机制对提交的计数器键值进行递增统计，统计维度包括今日、本周、本月、今年以及总数。在事务处理成功后，系统会调用xc_statistics_update方法，触发相关数据表的写入操作，从而实现Redis与SQL结合的全方位统计处理。由于该方法涉及的操作较多，且执行频率较高，在业务高峰期可能出现进程阻塞的风险。针对这一问题，系统进行了优化升级，默认情况下采用Swoole异步处理的方式来执行相关操作，以提升处理效率并降低阻塞风险。
9、鉴于后台已设置每日用户上传限制机制，为确保上传行为符合规定，根据用户身份类别（会员、非会员、商户、鉴定师）分别限制每日上传图片、视频和音频的次数。每当用户成功上传文件时，系统会通过 hook_success 触发行为计数器，具体操作流程为：首先通过 $upload['format'] 参数获取文件类型（如 image、video、voice 等），随后调用 xc_user_daily_hook 对用户的上传行为进行计数操作，将对应文件类型的上传次数增加 1。同时，根据文件类型的不同，对应的上传额度也会同步增加 1，以确保用户的每日上传操作能够受到精准的额度管控。这一机制不仅提升了资源管理的效率，也为不同身份用户提供了更合理的上传体验。
10、文件上传成功后，系统不仅会根据 $upload['format'] 文件类型触发对应计数器的处理逻辑，还会对文件的上传方式进行详细的计数统计。具体操作流程为：首先读取 $upload['method'] 参数以获取当前文件的上传方式，然后通过 xc_redis_count 对对应的计数器键值【upload_$upload['method']】进行累加处理，用以统计不同上传场景（如本地文件、FTP、SFTP、COS等）的文件同步数量。这种计数器的设计还支持日期维度的统计查询功能，用户可以查询特定时间范围内的上传数据，例如本周、本月、上周、去年等，方便对上传行为进行更精细化的数据分析与管理。
11、xc_upload_hook_success模块已完成封装与闭合处理，整个执行流程如下：首先，通过xc_upload_hook_afte注册动作钩子，用于后续的业务回调操作；接着，使用xc_query_upload方法读取上传对象数组中的详细信息；随后，调用update_redis_sorted_set对文件大小进行有序集合的统计；与此同时，通过xc_redis_count统计不同文件类型的上传成功数量；然后，使用xc_user_daily_hook记录用户每日各文件类型的上传额度消耗情况；此外，还通过xc_redis_count统计$upload['method']中的文件上传方式对应的同步数量；最后，利用xc_upload_image_config读取相应的配置信息，并根据配置执行相关事务处理。整体流程环环相扣，确保了上传逻辑的高效性与数据的准确性。

2025年6月4日
1、在xc_upload_hook上传钩子中，新增了对腾讯云对象存储（COS）同步的处理逻辑。当本次上传的媒体文件对应的主键ID【xc_upload媒体库表】返回的同步方式【$upload['method'] == cos】时，系统会识别该文件需要同步至腾讯云对象存储桶。此时，将直接调用xc_upload_cos_hook方法发起同步请求。同步过程中，系统会通过读取xc_upload表中的参数信息，获取【本地文件地址】和【对象存储文件保存路径】两个关键变量，并将其传递给COS同步逻辑进行处理。由于主要的业务逻辑均在xc_upload_cos_hook方法中完成，最终会直接返回原始数组结构，确保数据的完整性与同步结果的稳定性。
2、在通过宫论上传钩子处理COS文件同步任务时，系统会将执行结果存储到 upload_remote 变量中，并在任务完成后对该变量的内容进行验证与判断。如果检测到 upload_remote['code'] == 1，则表明上传操作失败，可能是由于【文件权限不足、接口异常、请求错误、参数不正确】等原因导致同步处理未能成功。此时，系统会立即返回相应的错误提示，并终止后续处理流程。同时，内部会详细记录相关的错误码及错误信息，以便后续分析与问题排查。
3、通过 COS 同步文件至对象存储桶，如果 upload_remote 返回的 code=0，则说明本次同步已成功完成。在此情况下，系统会自动触发 xc_update_sql 语法，对原有的媒体库记录进行回调更新。具体回调操作包括以下两点：首先，将媒体表中的状态字段 state 更新为 "OK"，以标记上传流程已完成，从而避免系统误判导致文件被重复上传；其次，读取 $upload_remote['url'] 中的远程访问地址，并将其写入媒体表的 remote 字段，以便后续通过该字段访问文件资源。这种处理方式确保了文件同步的准确性，同时为后续文件资源的调用提供了稳定的路径支持。
4、对xc_update_sql语法进行了优化升级处理，该语法主要用于同步更新指定数据表中的某行记录。本次升级涉及以下三个核心变量：1. 数据表名：通过该变量确定需要操作的数据表来源；2. update_data：包含待更新的字段及其对应值的数组结构；3. update_where：定义更新操作的条件。本次更新的重点在于增加了执行结果的返回功能，通过wp方法对更新操作的成功与否进行判断。如果更新成功，将返回true；若更新失败，则返回false。此功能的增强不仅提高了语法的可操作性，还为后续逻辑判断提供了更直观的依据。
5、xc_update_sql功能进一步优化，现已支持返回标准化的数组结构，提升了数据处理的规范性与可读性。其中，返回结果中的code字段用于标识执行状态：code=0表示数据表操作成功；code=1则表示操作失败。执行失败的常见原因包括SQL写入异常、参数缺失、条件不足、更新参数与数据表字段不匹配等问题。具体的错误详情可通过msg字段获取，系统会在操作失败时自动将错误原因写入msg字段并返回。这种基于数组结构的设计，能够确保错误信息在上级业务逻辑中顺畅传递，为后续的调试与问题定位提供了便利。
6、为了确保可溯源性，xc_update_sql正在执行过程中如果发生异常或者失败，系统会将对应的错误原因，通过日志系统记录下来，日志格式如下：[错误时间: - ' . date("Y-m-d H:i:s") . '] [用户: - ' . $upload['user_id'] . '] [错误日志: - ' . $e . '] [sql执行语句: - ' . $sql. ']，通过xc_log_error_warn内置语法进行写入处理，写入的日志标识为：uplpad_cos_error。通过日志形式记录上传接口的异常，方便后续运维人员分析接口异常的问题。注：宫论所有的日志都通过xc_log_error_warn来写入处理。
7、通过xc_upload_hook发起文件同步请求时，无论同步方式是【local、ftp、sftp、cos】中的哪一种，在执行xc_update_sql时都会对返回结果进行二次检查处理。如果返回值为code=1，则会立即终止整个处理流程，不再执行任何回调操作，而是直接返回对应的错误信息，提示用户上传失败并说明SQL写入异常。这一机制的目的是防止因SQL更新出现异常而错误判断为处理成功，从而引发后续不可控的情况。只有在确认SQL执行成功的前提下，才会继续执行相应的回调操作，确保流程的稳定性和数据的准确性。
8、通过xc_upload_hook成功上传COS文件后（SQL写入成功），系统会主动触发xc_upload_hook_success，该方法会传递【ID主键】以进行文件的回调处理。此方法是通用处理机制，无论采用何种方式进行上传，只要文件上传成功，就会主动触发并执行。执行的逻辑统一，确保处理流程的一致性。该方法是采用swwole异步去处理的，不会阻塞当前进程，可以理解为回调动作，需要主动触发，不需要关注具体的业务执行过程，不会有任何返回结果。
9、当COS同步事件完成回调处理动作后，整个执行流程随之结束。此时，系统会触发 xc_upload_hook_afte($id) 方法，注册动作钩子，以便进行外部业务的回调操作。该方法采用通用逻辑设计，能够适用于所有上传行为，并确保在上传完成后主动触发。同时，该方法依托 Swoole 异步处理机制运行，避免对主进程造成阻塞，从而保证系统的高效性与稳定性。在动作钩子成功挂载后，系统会将处理结果以标准格式返回，包括【code=0、msg=上传成功、type=cos、url=对应的CDN文件地址路径】，为后续业务逻辑提供明确的反馈信息和资源路径。
10、xc_uplpad_cos_hook功能进一步优化升级，现已支持通过local_file变量传递xc_upload主键ID值进行参数处理。在系统初始化阶段，local_file变量会经过is_numeric方法验证，以确认其是否为数字或数字字符串。如果验证通过，系统将调用统一查询方法【xc_query_upload】进行数据索引查询；若查询未能成功，则会尝试读取数据表中的【本地文件】字段，并按照上传逻辑执行后续处理。如果【本地文件】字段读取失败，则系统将返回错误提示：“上传失败：数据表记录查找失败”。这一升级不仅增强了参数处理的灵活性，还进一步完善了上传逻辑的容错机制。
11、系统通过xc_upload_cos_hook成功将文件同步至对象存储桶后，会触发一个Redis计数器【upload_cos】，用于记录服务器同步上传的文件数量。然而，该计数器仅统计上传文件的数量，并未涉及文件大小（size）的统计，因此无法有效监测对象存储桶的空间占用情况。为了解决这一问题，现对系统进行优化，新增一个【upload_cos_size】计数器。文件上传成功后，系统会自动读取本地文件的大小（size），并将该数据写入【upload_cos_size】计数器，从而实现实时统计每日、每周、每月的对象存储空间消耗情况。这一改进将进一步提升对存储资源使用情况的精细化管理，为后续容量规划和成本优化提供数据支持。

2025年6月3日
1、xc_uplpad_cos_hook文件负责将数据同步至腾讯云对象存储桶，其中涉及腾讯云SDK的加载与调用。为了实现上传功能，在初始化阶段会通过require_once加载【xc_sdk_composer】库，该composer库是宫论项目的SDK中心，内含所需的对象存储SDK。加载后，当前环境即可使用Qcloud命令执行上传请求。需要特别注意的是，所有的SDK均需通过composer包进行更新与维护，若出现版本更新情况，需及时升级以确保兼容性与功能完整性。
2、COS对象存储同步钩子在初始化时会封装一个remote_url变量，该变量由xc_upload_cos_domain（后台配置的CDN绑定域名信息）与remote_file（远程保存的目录地址及KEY名称标识）组合而成。在完成上传同步后，该变量将作为URL返回至前端，用于外网公开访问。由于默认的CDN加速域名与保存的文件路径名称是固定的，因此可以在初始阶段提前完成封装处理，仅需在上传完成后直接返回即可。
3、在完成基础拦截处理后，xc_uplpad_cos_hook会按照以下流程执行文件同步操作。首先，调用 new Qcloud\Cos\Client 方法，根据之前封装的参数构建上传对象的数组信息，并将构建后的对象保存到 cosClient 中。接下来，检测本地文件是否存在，若文件存在，则通过 $cosClient->upload 方法发起上传操作。上传时需要提供多个关键参数，包括 bucket（存储桶名称）、key（对象键，包含文件名及目录信息）以及 body（通过只读模式打开的本地文件）。最终，上传的处理结果会被保存到 cos_result 变量中，供后续使用或检查。
4、为确保系统的稳定性与可靠性，通过使用 xc_uplpad_cos_hook 发起的上传请求，采用了 try-catch 机制对整个流程进行严格处理，从而保证所有可能出现的执行错误或异常都能够被及时捕获并妥善处理。具体而言，该监听与处理机制覆盖了多个关键环节：从本地文件的 file_exists 检查开始，到 cosClient 对象的封装，再到上传操作的发起，直至最终结果的返回。无论哪个环节出现异常或错误，系统都会通过 catch 机制进行捕获，并返回统一的错误响应，其中包括 code=1 和对应的 msg 错误信息，同时立即终止整个执行流程，确保异常不会对后续操作造成影响。
5、如果通过xc_uplpad_cos_hook发起cos对象同步请求，try-catch返回异常行为会触发日志写入。日志格式如下：[上传时间: - ' . date("Y-m-d H:i:s") . '] [上传用户: - ' . $upload['user_id'] . '] [错误日志: - ' . $e . ']，通过xc_log_error_warn内置语法进行写入处理，写入的日志标识为：uplpad_cos_error。通过日志形式记录上传接口的异常，方便后续运维人员分析接口异常的问题。注：宫论所有的日志都通过xc_log_error_warn来写入处理。
6、COS对象存储作为当前系统中重要的上传接口，其主要功能是通过COS进行CDN分发处理。为了进一步提升系统的稳定性与运维效率，后台日志报警器新增了对“uplpad_cos_error”的支持。具体配置如下：当该接口在一天内连续发生错误次数达到30次时，将触发报警机制。报警内容会通过邮件、站内信和公众号三种形式通知管理运营人员，每日最多触发三次。每次触发后，系统会自动将错误计数重置为0，以确保后续监控的准确性。需要特别注意的是，此错误报警机制暂不支持短信提醒功能，但邮件通知会主动携带相关日志文件作为附件，便于运营人员快速定位问题并进行处理。
7、在文件上传功能中，如果通过 COS 对象同步 HOOK 钩子成功完成文件上传（具体依据 cos_result 变量的处理结果进行判断），系统将自动触发一个名为 "cos_upload" 的计数器，用于记录成功同步至 COS 的文件数量。这一计数器的设计旨在支持后续数据的多维度统计分析。通过调用 get_redis_count($key) 函数，系统可以灵活查询与该计数器相关的详细统计信息，包括上传文件的总数量、今日上传数量、昨日上传数量、本周及上周上传情况、本月与上月的文件统计，以及今年与去年的相关数据分析。值得注意的是，该计数器的触发条件严格限定为文件处理成功的场景，若在文件同步过程中因异常触发 try-catch 错误，则计数器不会记录任何数据，确保统计信息的准确性与可靠性。此功能为多维度数据分析提供了强有力的支持，同时也有效提升了系统的可追踪性与数据管理能力。
8、在xc_uplpad_cos_hook模块中，已全面接入hook_before脚本，所有拦截行为均统一通过hook_before进行处理。无论是系统内置的拦截机制，还是第三方通过过滤钩子注册的拦截方法，均需通过hook_before完成逻辑处理。xc_uplpad_cos_hook本身不再直接处理任何拦截行为，而是依据hook_before的返回结果进行响应操作。当hook_before返回的code值为1时，系统将立即返回对应的数组结果，同时终止后续的执行流程。需要特别注意的是，通过hook_before实现拦截处理的设计，赋予了第三方注册拦截行为的灵活性，但第三方必须按照标准的数组格式进行返回，以确保系统能够正确识别并响应拦截逻辑。这种机制优化了拦截流程的统一性和扩展性，为系统与第三方的交互提供了规范化支持。
9、同样的 xc_uplpad_cos_hook 也接入了 hook_afte 脚本机制，当文件成功同步到 COS 对象存储后，会立即触发 xc_uplpad_cos_hook_afte 回调脚本。该脚本会将两个关键变量传递至指定处理逻辑：其一是 local_file，即本地文件的绝对路径地址；其二是文件在对象存储中的外网 CDN 访问地址，用户可以直接通过该地址请求访问上传的文件。随后，回调脚本会触发 xc_do_action 动作，该动作通过 Swoole 异步通知机制，将上传成功的消息通知给挂载的处理方法，并同步告知接口，确认文件已上传并处理完毕。这种流程设计不仅实现了文件上传后的快速反馈，还为后续的文件访问和业务处理提供了便利和效率保障。
10、当xc_uplpad_cos_hook完成所有处理工作后，将返回以下固定变量：code=0，表示本次文件同步任务顺利完成，文件已成功上传至对象存储桶；msg=文件上传成功，用以提示前端用户文件处理已结束；type=cos，告知系统本次上传操作采用了COS对象存储的方式；url=绑定对象存储的CDN域名+文件目录+文件名，生成前端可直接使用的资源访问地址。这些变量确保系统能够准确记录文件处理结果，同时便于前端快速获取资源。需要特别注意的是，无论是通过本地上传、远程服务器、FTP/SFTP，还是云厂商对象存储完成文件上传，返回结果都必须包含上述四个固定变量，以保证上传流程的一致性和系统间的联动性。
11、xc_upload_cos_hook已完成封装处理，该钩子功能旨在将本地文件高效同步至COS（对象存储）。整个执行流程设计严谨，确保上传过程的稳定性和安全性。具体步骤如下：首先，通过hook_before执行拦截行为，对请求的合法性进行校验，确保上传操作符合预期规则；接着，根据后台的配置信息动态构建COS客户端（cosClient）的上传对象数组，为后续操作提供必要的参数支持；随后加载composer环境，确保COS所需的SDK能够正常被读取和初始化；完成环境准备后，调用$cosClient->upload进行实际上传操作，并对返回的结果进行实时监听，确保上传状态的透明性和可追溯性；最后，触发hook_after回调通知，将上传结果以数组结构返回，为后续业务处理提供数据支撑。整个执行流程不仅支持日志记录和报警机制，还内置了计数器处理逻辑，同时通过try-catch对可能的错误进行精准捕获，提升了系统的鲁棒性与容错能力。

2025年6月2日
1、完成xc_upload_hook上传处理脚本的迁移工作，将其从原本的HOOK.php调整至新脚本hook_vice.php。这次迁移的主要目的是为了优化后续的维护与更新流程。原本的HOOK.php脚本主要用于处理旧版本的钩子事件，这些事件的功能相对次要，且脚本语法存在较多不完善之处，无法实现标准化的执行流程。而新设计的hook_vice.php则是经过重构优化的脚本，采用更加规范的语法结构，严格遵循宫论标准，确保执行过程的高效与稳定性。此次迁移也明确了一项原则，即凡是涉及到重构处理的HOOK事件，必须从HOOK.php迁移至hook_vice.php，这不仅提升了维护效率，同时也标志着该钩子事件已完成重构，符合设计规范要求。
2、xc_upload_hook新增了hook_before拦截动作事件，旨在优化上传流程的灵活性与可扩展性。当系统或用户触发上传行为时，除了执行内置的基础拦截处理流程外，还会主动调用xc_upload_hook_before拦截触发器。触发器运行时会将媒体库唯一主键ID作为参数传递，供后续处理使用。同时，内部通过xc_apply_filters机制介入并过滤钩子，允许开发者通过add_filter方法动态接管函数执行逻辑，以实现更深层次的定制化。如果第三方需要扩展或加入新的拦截处理流程，可以通过注册方法来添加自定义拦截逻辑。需注意，注册方法必须返回符合标准的数组结构，以确保系统能够正确解析并完成响应处理，从而保持功能的稳定性与兼容性。
3、为进一步提升业务逻辑的规范性与可维护性，现已全面优化上传流程，将所有拦截行为整合至 xc_upload_hook_before 中统一处理。原先在上传内部执行的基础拦截逻辑已完全移除，upload_hook 的职责也得以简化，仅需专注于具体的业务执行。无论是系统内置的拦截规则，还是第三方插件介入的拦截逻辑，均统一由 xc_upload_hook_before 负责处理。该模块在完成拦截响应后，会对返回结果进行严格校验：若返回值中的 code=1，则立即中断后续操作，并直接返回对应的数组数据；若返回值为 code=0，则表示拦截通过，系统将继续执行后续流程。这一调整不仅优化了上传逻辑的清晰度，还为未来扩展和接入更多拦截规则提供了更强的灵活性。
4、在宫论上传的hook处理中，由于所有拦截逻辑均在before阶段执行，导致upload数组对象无法正确生成（该数组原本由拦截脚本动态创建），从而在执行SQL处理的回调时触发了致命性错误。为了解决这一问题，我们在完成before拦截动作后，引入了一个关键步骤：系统会通过调用xc_get_sql方法读取媒体库的主键ID值，并将其重新赋值到upload数组中。这样一来，可以确保后续的执行流程能够准确地获取到媒体库相关的参数信息，避免因数组缺失而导致的错误，为整体功能的稳定性提供了有效保障。
5、在原有的宫论文件上传请求HOOK钩子的基础上，新增了一个名为hook_after的回调脚本。对应的回调函数为：xc_upload_hook_afte。当本地待处理文件成功通过内置接口上传至远程服务器（包括云端对象存储）后，该回调脚本将被自动触发。触发时会附带一个ID参数，该ID为xc_upload表的主键ID值。通过该ID可以进一步获取远程服务器上的文件访问地址，具体可通过字段remote进行提取和使用。
6、当xc_upload_hook_afte触发时，会执行xc_do_action动作，该动作是宫论框架中的内置回调方法。在触发过程中，会动态传递__FUNCTION__（可理解为方法名称或触发标识）以及func_get_args（用于继承当前方法的变量参数）。通过这两个动态数组参数结合do_action方法，系统为第三方脚本提供了灵活的回调机制，使其能够在文件上传成功后接收到通知，并进一步执行对应的业务逻辑。需要注意的是，该方法仅用于发送通知，框架不会对处理结果进行接管，确保业务逻辑的独立性和灵活性。
7、针对xc_do_action方法进行了升级优化处理。该方法通过WordPress内置的do_action机制挂载并触发外部（第三方）注册的函数，主要用于在HOOK钩子完成业务逻辑后，通过调用该方法实现业务回调的功能。本次优化的重点在于提升回调通知的执行效率，为避免阻塞进程，回调的触发改为使用Swoole异步方式进行处理。这种异步优化不仅能够显著提高任务的并发能力，还减少了主进程的等待时间，从而提升系统整体性能。同时，为确保回调逻辑的稳定性，在触发Swoole异步执行前，会通过is方法检测当前是否处于异步环境中，如果已经处于异步状态，则会跳过Swoole的相关处理，避免重复或不必要的操作。此次升级进一步完善了回调机制，优化了任务处理流程，为后续扩展提供了更高效、更灵活的技术支持。
8、xc_upload_hook方法完成了全面重构，其职责更加专注于核心业务逻辑的处理。拦截动作现已拆分至独立的xc_upload_hook_before模块，能够支持外部第三方事件的接入，且无需对源代码进行任何修改即可实现新的拦截功能。业务回调方面，通过xc_upload_hook_after($id)模块完成处理，同样支持在不修改源代码的情况下，将上传成功的相关信息发送至外部方法，并借助swoole实现异步回调执行，大幅提升了系统的扩展性与运行效率。
9、新增了 COS 对象存储文件上传同步的 HOOK 钩子：xc_upload_cos_hook()。该钩子专门用于实现将本地服务器上的文件同步到腾讯云对象存储。此方法需要传递两个关键变量：$local_file 和 $remote_file。其中，$local_file 表示本地文件的路径，需填写绝对路径。如果文件并非直接存储在服务器本地，则需先将其下载至本地后再进行操作；而 $remote_file 则代表远程文件的存储路径，包括目标目录及文件名。值得注意的是，以往 COS 同步功能是直接通过 xc_upload_hook 实现的，但由于后台扩展性需求，系统需支持多种上传同步方式，因此该方法进行了优化并独立出来，原有的实现方式将被逐步摒弃。
10、为确保业务逻辑的统一性，现对xc_upload_cos_hook的返回结构进行规范化调整，统一采用标准的数组结构。在正常情况下，该结构将固定返回两个参数值：code和msg。其中，code用于表示处理状态，具体定义为0和1两个取值，0表示处理成功，即文件已成功同步到对象存储；1表示处理失败，失败的原因可能包括但不限于文件查找失败、请求失败、权限不足或账户欠费等多种情况。为了便于定位问题，当code为1时，msg字段将返回具体的失败原因；而在上传成功时，msg字段的值将固定为“文件上传成功”。这种规范化的返回结构有助于提升系统的可读性和问题排查的效率。
11、在初始化阶段，xc_uplpad_cos_hook 会通过 xc_get_option 方法读取一系列关键参数信息，包括 secretId（腾讯云秘钥参数 ID）、secretKey（腾讯云秘钥参数 key 值）、region（存储桶地域参数）、bucket（存储桶名称，固定值）以及 cos_domain（COS 自定义域名信息，可理解为 CDN 加速域名）。这些参数均为系统之前已封装完成的内容，此处仅作提取操作。在完成账户参数的封装后，系统会通过 file_exists 方法对 local_file 本地文件进行检查，以确保文件的存在性和可读性。如果文件不存在或读取失败，系统将返回错误提示：“上传失败：本地文件不存在”，以便及时提醒用户并避免后续操作中可能出现的错误或异常。

2025年5月30日
1、在处理MIME类型为【video视频】的文件上传时，upload.php新增了一项逻辑优化：当读取到xc_upload_method配置信息后，如果同步类型不是local本地存储，并且启用了xc_upload_local_synchronous参数配置，那么在返回给前端之前，将通过unlink函数删除本地存储的文件，以释放服务器磁盘空间。这一删除操作的执行需满足以下三个关键条件：第一，文件必须已成功同步到远程服务器，确保数据完整性；第二，文件的存储方式不能为本地存储；第三，已明确开启xc_upload_local_synchronous选项配置。此逻辑不仅优化了服务器资源管理，还提升了系统运行效率，但需要特别注意同步状态的准确性与配置参数的合理性，以避免误删数据导致潜在问题。
2、针对xc_upload_hook宫论远程文件同步HOOK的重构处理，本次调整重点在于优化其功能和扩展性。该钩子负责传递一个固定变量id（即宫论上传媒体库数据表的主键ID），在upload.php脚本完成文件本地上传后，系统会将上传记录写入到xc_upload数据表，并随后触发HOOK钩子以启动远程文件的同步操作。由于该HOOK是早期设计，存在不少细节上的缺陷，尤其是其功能仅支持COS对象存储桶的同步，难以适配当前日益多样化的上传需求。为此，本次重构将从功能扩展入手，优化其逻辑和兼容性，确保其能够支持多种存储类型的远程文件同步，同时完善相关配置和处理流程，以满足未来复杂的业务场景需求。
3、xc_upload_hook 之前采用的是早期设计的 xc_get_sql 方法进行数据表的读取与处理，该方法在当时能够满足基本需求。然而随着业务复杂性的提升，旧方法逐渐显现出性能和灵活性上的不足，因此团队对查询逻辑进行了重构，设计了一个具备缓存处理的统一查询方法——xc_query_upload。为了实现向上兼容，旧方法需要进行调整并升级为 xc_query_upload。在使用该方法读取媒体库记录时，系统会优先通过 Redis 缓存进行数据查询，从而显著提升响应速度，避免直接通过 SQL 执行请求。这种优化不仅确保了查询效率，还有效减少了数据库压力，为后续复杂业务场景的扩展提供了更稳定的技术支持。
4、宫论统一上传脚本优化：对xc_upload_hook的拦截处理机制进行了全面优化。首先新增了empty检测机制，用于校验传递的ID是否存在，若ID为空，则直接视为非法请求；如果ID存在但不为纯数字类型，则判断为参数异常。对于符合条件的ID，系统会通过xc_query_upload查询数据表记录，若查询失败则直接返回异常提示；查询成功后会进一步校验state状态，过滤掉“已上传成功”和“已删除”这两种状态，确保操作仅针对有效记录。随后从数据表中提取local字段的本地文件路径，并对文件进行严格检测，确保文件真实存在且为远程的本地图片文件，从而提高上传脚本的可靠性与安全性。
5、为优化数据管理和提升业务处理效率，xc_upload数据表新增了两个重要字段：1、method：用于记录上传同步方式。由于远程同步方式具有多样性，新增该字段旨在明确每个文件的具体处理方式，便于后续业务操作时能够准确识别和执行相应处理逻辑。字段类型设定为varchar，以确保能够灵活记录不同的同步方式。2、update_time：用于记录数据表的最后变更时间。无论是文件删除、机器审核、远程文件同步成功，还是媒体信息写入处理等操作，只要涉及数据表更新，该字段都会自动触发更新。字段类型设定为DATETIME，并配置DEFAULT CURRENT_TIMESTAMP和ON UPDATE CURRENT_TIMESTAMP属性，确保在数据插入或更新时能够实时记录当前时间，为数据追踪和变更记录提供可靠支持。这两个字段的新增，不仅完善了数据表的功能，还为后续业务流程的精确管理和高效处理奠定了基础。
6、在宫论的上传脚本【upload.php】初始化过程中，脚本会通过调用 xc_get_option 方法读取系统配置项 xc_upload_method 的信息，并将其存储到变量 upload_method 中，以便后续使用。在执行 xc_insert_sql 语法时，脚本会将上传方式信息写入到 upload_data 数组中的【'method' => $upload_method】字段，从而确保在媒体库数据表建立记录时，能够同步将上传方式写入到对应字段中。值得注意的是，由于整个上传脚本涉及大量文件上传处理场景，因此需要在所有执行 xc_insert_sql 操作的地方加入这一处理逻辑，以确保适配所有可能的上传场景并实现上传方式的统一记录与管理。
7、在宫论媒体库数据表中，由于新增了method字段，该字段用于指示当前文件的远程同步方式，因此在xc_upload_hook执行过程中需对该字段进行严格的检查和处理。如果method字段为空，将直接返回【上传失败：method字段缺失无法操作】，以确保操作的规范性和数据的完整性。如果method字段不为空，则进一步判断其值是否为local，若为local则表示该文件无需进行远程同步处理。在这种情况下，将执行以下操作：首先，通过home_url函数获取当前网站的域名信息，然后将该域名与数据表中的【remote】字段进行拼接，从而生成本地服务器文件的完整访问路径。最后，调用xc_update_sql($table_name, $update_data, $where)进行更新处理。
8、当$upload['method']设置为local时，在完成xc_update_sql的同步操作后，上传脚本会通过xc_upload_hook_success触发文件上传成功的回调动作，以确保后续处理能够顺利执行。此时，系统会立即返回以下数组信息：code=0（表示本次上传操作成功），msg（提示信息：文件上传成功），type（上传类型：local，指本地上传），url（通过当前域名、上传路径地址和文件名拼接而成，用于外网资源的访问）。该URL为最终生成的外部访问路径，便于资源的后续使用。在上述过程完成后，脚本会终止进一步处理，标志着本地资源的上传工作已结束并成功退出。
9、当系统读取到的上传方式为FTP或SFTP时，本次文件上传需通过【远程服务器】进行处理。为此，系统会调用 xc_hook_upload_remote() 方法以进行上传的准备工作。上传过程所需的关键参数包括以下内容：key 参数通过读取后台配置项 xc_upload_ftp_method 获取，该配置项用于定义FTP或SFTP上传的预设KEY。如果系统未能成功读取该参数，则会直接返回错误，并提示用户：“上传失败：远程服务器的KEY参数为空，请联系管理员进行处理！”。此外，local_file 参数直接从 $upload['local'] 中读取，而 remote_file 则从 $upload['remote'] 中获取。这些参数共同构成了远程上传的必要信息，用于确保文件能够顺利完成上传到目标服务器。
10、在远程文件上传处理流程中，xc_upload_hook会根据上传方式的method字段判断是否为【FTP或SFTP】模式。如果是这两种方式，整个执行流程将完全交由xc_hook_upload_remote进行处理，包括同步操作、SDK加载、错误拦截及日志回调等复杂逻辑。在xc_upload_hook内部，只需完成两项核心操作：第一，直接将xc_hook_upload_remote返回的结果原封不动返回，因为结果数据均为标准的数组结构，便于直接传递；第二，当返回的code值为0时，表明远程文件上传已成功。此时，为了确保业务逻辑的一致性，还需额外调用xc_upload_hook_success($id)来执行上传成功的回调操作。这一设计既简化了xc_upload_hook的职责，又确保了不同上传方式下的处理统一性与可靠性。
11、鉴于xc_hook_upload_remote的应用场景并不局限于【用户前端（图片、视频）上传】，还涉及日志同步、数据文件同步、文件备份等更广泛的处理需求，因此不再计划在该方法内直接处理【xc_upload】数据表的相关业务逻辑，而是将其交由上级逻辑统一处理。具体实现方式为：当xc_upload_hook触发该事件后，只需判断返回结果中的code是否为0，若为0则执行xc_update_sql数据表的回调操作。回调写入的参数包括以下内容：【state：ok，表示本次远程文件已成功传输至指定服务器，上传任务已圆满完成；remote：文件的外网访问地址，可直接读取$upload_remote['url']】。完成回调操作后，系统将返回一个处理成功的数组结构，标志整个执行流程结束。

2025年5月29日
1、xc_hook_remote现已支持日志监听功能，能够精准记录上传过程中出现的错误情况。无论是通过FTP还是SFTP协议进行文件上传，只要返回值为code=1，系统将自动触发错误日志记录，确保问题能够及时追踪与定位。错误日志的格式包括以下内容：上传时间、发起上传请求的用户（如果为非系统任务，则记录具体用户信息）、上传文件的本地地址路径、上传的KEY标识（对应同步的服务器信息）、以及msg字段记录具体错误原因。所有错误信息将统一写入到upload_remote标识，并通过xc_log_error_warn方法进行日志写入与处理，从而提升系统的错误监控能力及日志管理效率。
2、在通过xc_log_error_warn写入远程服务器文件上传日志错误时，系统会自动触发管理运维人员的报警通知。具体配置参数为：当upload_remote错误日志在当天累计达到20条时，就会通过【短信、邮件、公众号】进行消息推送，提醒运维人员远程服务器同步出现异常，需及时处理。如果采用邮件方式，系统还会自动将日志文件作为附件发送到运维人员的邮箱。该日志报警机制每天最多触发三次，超过三次则不再触发，以防止重复推送。每次发送后，系统会重置错误条目，从0开始重新累计。
3、宫论的上传配置页面新增了一个字段【xc_upload_method】，用于选择文件上传的存储方式。该字段采用了sorter类型设计，提供多种选项以适应不同的使用场景。目前支持的方案包括：local，即本地服务器存储，所有文件都直接存放到服务器上，不进行分发；cos，利用腾讯云的对象存储，将文件同步到存储桶并通过CDN进行分发；ftp，通过FTP或SFTP协议，将文件分发到远程服务器以进行进一步处理。用户可以根据实际需求选择适合的上传同步方案，从而优化文件存储和分发的效率与安全性。
4、在上传配置页面新增了一个开关选项字段【xc_upload_local_synchronous】，用于控制上传文件是否需要在本地进行存档处理。若开启该选项，上传的文件（如图片、视频、音频）在成功上传至远程服务器后，系统会主动在本地保存一份备份；若未开启，则本地文件在同步至远程服务器成功后会自动删除。需要注意的是，该字段仅在【xc_upload_method】字段的选项不为“local”时才会显示。也就是说，当上传类型选择非本地存储时，系统会提供此选项，用于决定上传至存储桶或远程服务器的文件是否需要额外在本地进行备份处理。
5、对xc_upload_method字段的类型进行了优化调整。此前，该字段类型设置为sorter，虽然其本质是一个数组类型的配置，但在实际读取配置时，会出现解析错误的问题。原因在于上传类型通常是唯一值，例如选择本地服务器时，该字段的返回值应为local，而不是一个数组结构的参数。为解决这一问题，现将字段类型调整为select，保持字段结构不变，依旧支持local、cos、ftp三种上传类型，但改为单选模式，避免因多选导致的解析异常，从而提升配置的稳定性和准确性。
6、在上传配置页面新增了字段【xc_upload_ftp_method】，字段类型为文本类（text）。该字段用于配置FTP或SFTP上传的关键识别码（KEY），主要用于远程服务器同步场景中账户信息的识别。由于远程服务器的账户信息是以数组形式存储的，系统需要通过该KEY来精准定位和读取对应的服务器信息，确保文件上传和同步流程的正常进行。如果用户选择了FTP或SFTP作为同步方案，则必须主动填写此KEY，用于配置账户信息。需要注意的是，该字段仅在【xc_upload_method】的值等于FTP时才会被触发，其他同步方式不会涉及此配置。通过此设计，进一步增强了系统在多服务器环境下的灵活性与稳定性。
7、宫论秘钥账户配置页：在配置组xc_appkey_sftp_config中新增了一个字段“url”，用于存储远程服务器绑定的域名地址，例如：https://cdn.gonglun.vip/upload/。该地址是实际文件访问的外部路径，能够映射到远程服务器的指定目录。当用户通过FTP/SFTP上传或同步文件至远程服务器后，系统将根据该域名地址动态生成文件的外网访问路径，例如上传文件“1.mp4”，系统会自动拼接生成完整的访问地址为：https://cdn.gonglun.vip/upload/1.mp4。为了保证文件能够正确访问，系统在创建FTP/SFTP账户时需提前处理好路径映射逻辑，确保能够准确生成文件的外部访问地址，为用户提供便捷的文件访问服务。
8、在使用xc_hook_sftp和xc_hook_ftp成功上传文件后，系统会额外返回一个URL字段。这个字段是通过读取配置中的URL字段，并与传递的remote_file字段进行拼接处理后生成的，目的是获取文件的外网访问路径。为了提升用户体验，当用户上传文件时，如果后台设置要求文件需要同步到SFTP或FTP，那么在同步成功后，系统会将生成的外网访问路径返回给前端。这一改进允许用户在前端界面上直接查看和访问上传的资源，从而弥补了之前未考虑到的这一层处理。
9、新增了一个全新的 HOOK 方法：xc_hook_upload_remote，用于处理远程服务器文件的同步上传。此方法作为 xc_hook_remote 的平替方案，传递的参数与之前保持一致，但无需进行中转处理。它能够根据协议类型自动整合 FTP 和 SFTP 的功能，通过配置或参数动态选择适用的协议进行文件上传操作。该方法设计简洁高效，统一了 FTP 和 SFTP 文件上传的逻辑，实现了上传方案、日志记录以及返回结果与之前内置方法的一致性。这种方式不仅优化了文件同步的处理流程，还为后续的功能扩展和维护提供了更大的便利性和灵活性。
10、xc_hook_upload_remote作为统一的FTP/SFTP上传解决方案，其变量参数设计基本沿用了之前HOOK的逻辑，但针对URL（外网文件访问路径）的输出处理进行了优化和调整。其中，remote_file参数，即远程保存的KEY文件名，从原先的可选变量升级为强制传递项。这一改动的目的是为了确保在构建URL地址参数时，能够精准获取真实有效的外网访问路径，从而避免因参数缺失而导致的访问异常或数据错误。需要特别说明的是，此次调整主要基于URL访问的必要性，而此前由于仅关注文件同步状态，对URL的处理未作严格要求。
11、宫论统一上传脚本：upload.php。该脚本负责处理上传请求，特别是当请求的来源标记为blob且类型为图片时，会自动读取xc_upload_method配置以确定远程上传方式。如果配置返回值不是local（本地服务器存储），则意味着此次上传需要进行远程服务器同步处理。在这种情况下，脚本会通过xc_upload_local_synchronous参数来验证是否启用了本地文件存储方案。如果该参数设置为false，则在文件成功上传后，会使用unlink函数删除本地存储的文件，以释放服务器的磁盘空间。需要注意的是，这个删除动作需要满足以下三个条件：首先，文件必须已经成功同步到远程服务器；其次，文件存储方式不是本地存储；最后，已启用xc_upload_local_synchronous选项配置。

2025年5月28日
1、xc_hook_ftp已优化为通过try-catch机制捕获异常，确保在异常情况下不会错误返回。整个钩子的执行流程已被完整封装，具体步骤如下：首先，使用file_exists函数检测待上传文件是否存在，若不存在则立即返回错误信息。接着，读取关键配以确认场景配置是否存在，若缺失则返回错误；若配置存在，则检查协议选择是否为FTP，若不是则返回相应的错误提示。在确认配置后，读取场景的其他配置，通过ftp_connect函数构建上传请求，若在构建过程中发生异常，将返回相应的错误信息。随后，调用$ftp_put方法执行上传请求，并监控返回结果，若发生错误则返回对应的错误信息。最后，上传请求成功完成后返回code=0，并通过ftp_close函数关闭上传接口。
2、在通过 xc_hook_ftp 发起 SFTP 协议请求时，为了确保异常错误能够及时捕获并处理，系统会通过 try-catch 机制进行监听。如果在以下任意环节发生错误：构建 ftp_connect 对象时发起登录请求失败、通过 ftp_login 发起连接登录请求失败、或使用 ftp_put 发起文件上传请求失败，均会触发 catch 块捕获异常并返回对应的错误信息。在捕获到错误后，系统会拦截并记录相关的上传操作信息，包括上传时间、上传的 KEY 参数、上传的本地文件地址、上传人及具体的错误信息。这些信息将以日志形式写入到【ftp_error】日志文件中，确保问题能够被追踪和定位。日志记录的写入通过调用宫论方法 xc_log_error_warn($key, $log) 实现，以标准化的方式保存错误信息，为后续的排查和处理提供可靠的数据支持。
3、通过使用 xc_hook_ftp 成功将本地文件同步至 FTP 服务器时，会激活 Redis 计数器。该计数器的标识为 ftp_upload，用于记录 FTP 文件同步的数量。用户可以通过 get_redis_count($key) 函数来获取详细的统计信息，支持多维度的数据分析，包括查询总数、今日、昨日、本周、上周、本月、上月、今年和去年等。值得注意的是，只有在文件处理成功的情况下才会触发计数器，如果在同步过程中出现 try-catch 错误，则计数器不会被触发。设置该计数器的目的是为了有效统计 FTP 服务器的文件同步处理数量，帮助进行全面的数据分析和监控，从而优化系统性能并提升服务质量。通过该计数器，用户能够实时掌握文件同步情况，及时发现和解决潜在问题，确保数据传输的稳定性和可靠性。
4、xc_hook_ftp模块的封装处理已完成，其执行流程设计清晰且严谨。首先，系统会读取后台的配置信息，并结合提供的密钥参数进行校验，以确保能够正确获取对应的服务器账户信息。如果账户信息读取失败或账户已被停用，系统会立即返回错误提示，避免后续操作的进行。接下来，系统尝试访问本地文件local_file，如果文件不存在或用户权限不足，同样会返回错误信息，确保操作安全性。在完成文件校验后，系统通过FTP扩展模块构建并发起FTP请求，尝试登录服务器并执行文件上传操作。在整个上传过程中，系统对可能出现的任何错误进行捕获，及时返回错误信息，并通过日志记录详细的错误原因，便于后续排查问题。如果文件上传成功，系统会通过Redis执行计数器操作，返回code=0以标识操作成功。最后，系统关闭FTP对象以释放资源，确保运行效率和稳定性。整个流程设计合理，充分考虑了安全性、稳定性和容错性，具备较强的实用价值。
5、同样地，为了更高效地处理回调事件，xc_hook_ftp方法新增了一个callback脚本功能。当文件成功同步至FTP服务器后，系统会自动传递以下参数供回调事件使用：1. user_id：用于标识当前上传操作的用户，确保用户信息与上传行为精准匹配；2. local：指本地上传文件的路径或名称，方便定位文件来源；3. key：作为上传服务器的唯一标识符，用于区分不同的上传任务；4. remote：代表远程文件的地址标识，用以确认文件在FTP服务器中的存储位置。这些参数的传递不仅保证了回调事件能够准确获取上传文件的相关信息，还为后续处理和操作提供了可靠的数据支持，进一步优化了系统的功能性与实用性。
6、callback回调脚本在成功接收到FTP文件上传请求的响应事件后，会即时通过xc_do_action(__FUNCTION__, $result, func_get_args());注册外部动态动作钩子。此操作的核心在于触发动态钩子时能够将相关变量完整地传递给挂载函数，从而实现灵活的事件处理机制。一旦该方法完成注册，外部可以通过add_action方法自由添加挂载函数，这使得开发者无需修改源代码便能轻松接收上传成功的通知事件并进行后续处理。值得一提的是，该实现基于标准化的动态过滤钩子集成方案。注：FTP和SFTP两个上传场景，触发机制和执行逻辑基本保持一致！
7、在xc_hook_ftp模块中集成了基于Swoole的异步处理方案，并新增了一个可选变量【asyn】以控制异步行为。该变量默认值为false，即默认情况下上传请求通过同步方式执行；如果将其设置为true，则当前上传请求将通过Swoole服务器进行处理，实现异步上传。这一设计旨在根据实际使用场景灵活选择上传方式：对于系统任务中需要执行的大量上传操作，建议启用异步处理，以避免因同步执行导致的超时问题；而对于用户实时上传的场景，则应禁用异步处理，以确保前端页面能够及时获取上传结果，提升用户体验。通过这一优化，模块可以在性能和响应速度之间达到更好的平衡。
8、xc_hook_ftp和xc_hook_sftp均为实现本地文件云同步到远程服务器的关键方法，其核心区别在于传输协议的选择——前者通过FTP协议进行文件传输，后者则采用更安全的SFTP协议。两者在执行机制上基本一致，对应的账户配置集中在同一字段组内，能够根据不同的业务场景灵活选择适用的协议进行文件传输。这一远程服务器同步功能不仅限于图片和视频的传输处理，还涵盖日志备份、数据备份以及本地文件的多维度备份，应用场景极为广泛。同时，该功能还将持续扩展和优化，主要配合宫论的定时计划任务，完成核心数据的实时异步存档工作，从而有效保障平台数据的异地容灾能力，为业务稳定性和数据安全性提供坚实支撑。
9、目前，xc_hook_ftp和xc_hook_sftp均通过读取xc_appkey_sftp_config配置来解析远程服务器的账户信息，其执行逻辑大体一致，仅在协议层面存在差异。为进一步优化代码结构并提升系统的可维护性，决定新增一个通用方法，以同时兼容FTP和SFTP两种协议。在实现上，该通用方法将通过解析KEY获取协议类型（TYPe值），系统会根据解析结果自动加载对应的SDK或扩展模块，从而完成远程上传请求的发起。这样一来，开发过程中无需再区分具体使用的是FTP还是SFTP协议，统一通过通用方法即可实现上传功能，既简化了调用流程，也增强了代码的灵活性和扩展性。
10、新增处理HOOK钩子【xc_hook_remote】，该钩子专门用于实现本地文件与远程服务器之间的同步功能（注意：此功能不涉及云厂商的对象存储同步，仅支持FTP和SFTP协议的文件传输）。在使用该HOOK时，需主动传递三个固定变量和一个可选变量，以确保同步任务的正确执行。具体如下：1、key：该参数对应后台配置项xc_appkey_sftp_config，用于判断并验证所采用的协议是FTP还是SFTP，确保传输方式与配置一致。2、local_file：指本地文件的完整路径，需同步的文件必须存在于本地服务器，且路径需明确无误。3、remote_file：远程服务器上文件存储的目标路径，该路径需在调用前预先封装好，以确保文件能够准确保存到指定位置。4、asyn：此为可选参数，用于控制同步任务的执行方式。默认值为false，表示同步执行；若需要异步执行，则需显式设置为true。通过以上参数的灵活组合，该HOOK能够高效地完成文件传输任务，同时满足不同场景下的需求。
11、xc_hook_remote的处理流程相对简单明了，主要实现了基础拦截验证，并根据配置文件的内容选择合适的上传协议进行中转处理。具体来说，它首先会读取xc_appkey_sftp_config配置文件，根据返回的type值决定调用xc_hook_ftp或xc_hook_sftp方法。整个流程的核心在于根据不同的协议类型执行对应的HOOK操作，而具体的上传行为并不是由该方法直接实现，仅充当一个协议中转的角色。基础拦截的逻辑包括以下几个步骤：首先，通过file_exists检测本地文件是否存在；其次，使用xc_get_option读取xc_appkey_ftp_config配置文件，若读取失败则直接返回错误；在成功读取配置后，还需验证open状态是否开启，若未开启则同样返回错误；最后，根据配置文件中$config['type']的协议类型，选择对应的上传HOOK进行调用。这种设计思路有效地分离了具体上传逻辑与协议判断，确保流程清晰且易于维护。

2025年5月27日
1、在xc_hook_sftp方法中新增了一个回调事件，该事件的处理逻辑被封装在callback.php脚本中。此脚本是宫论项目中所有回调事件的集中处理模块，旨在简化管理和维护工作。当前维护脚本的执行时机是在文件成功同步到SFTP服务器后，触发并执行。此时，会传递以下参数以供回调事件使用：1、user_id：标识本次上传的用户。2、local：本地上传文件的路径或名称。3、key：用于标识上传服务器的唯一标识符。4、remote：远程文件的地址标识。这些参数的传递确保回调事件能够准确获取上传文件的相关信息，以便后续处理和操作。
2、callback回调脚本在接收到sftp文件上传请求成功响应事件后，会立即通过xc_do_action(__FUNCTION__, $result, func_get_args());注册外部动态动作钩子，在触发的时候会将携带的变量一并传递过去。该方法一旦注册后，将允许外部通过add_action方法来注册挂载函数。注册挂载的函数，可以在不修改源代码的基础上，接收到上传成功的通知事件。注：采用的是标准化方案来集成动态过滤钩子，允许同时接收多个方法来处理回调业务。
3、在xc_hook_sftp模块中新增了一个名为asyn的变量，用于灵活控制上传请求的执行方式。默认情况下，该变量设置为false，意味着当前上传请求将采用同步方式进行处理和响应。这种方式适合需要立即确认上传结果的场景。然而，如果将asyn变量设为true，系统会自动将请求转发到异步进程中进行处理，利用swoole技术实现异步上传和后续业务逻辑的处理。这种异步方式特别适合不需要立即获取上传结果的场景，因为它能够避免阻塞进程，从而提高响应速度和系统效率。选择同步或异步上传方式应依据具体的使用场景进行判断：如果上传操作需要实时确认成功与否，则应坚持同步方式；而在不需要立即确认结果的情况下，异步执行则是更优的选择。
4、宫论服务器在最新的【PHP：8.3】版本中正式集成了FTP扩展功能，使得开发者可以通过PHP脚本利用内置扩展插件进行FTP服务器的文件同步操作。此前，系统主要依赖phpseclib3脚本实现SFTP协议的文件同步处理。尽管SFTP协议以其安全性和可靠性著称，但其使用需要通过SSH账户密码进行登录验证，若远程服务器出于安全考虑未开放SSH登录选项，SFTP便无法使用。因此，为了增强系统的兼容性和灵活性，除了继续支持SFTP协议外，宫论服务器还加入了对传统FTP协议的支持。这一举措确保了远程服务器文件同步的高扩展性和高可用性，为用户提供了更多选择以应对不同的网络环境和安全要求。
5、新增了宫论FTP上传方法的HOOK事件：xc_hook_ftp。该方法的命名规则与现有的SFTP上传HOOK事件保持一致，仅在后缀上有所区别，一个为FTP，一个为SFTP。这一方法主要用于实现通过FTP协议上传文件的功能，并支持灵活的配置与调用。在实际使用中，该HOOK事件需要传递以下变量参数：key，用于匹配FTP配置的键值，后台会根据此键值获取对应账户的相关配置信息；local_file，即本地文件的完整路径，用于指定需要上传的文件；remote_file，表示远程文件的存储路径，此参数通常是可选的，因为文件存储的具体目录一般由后台进行定义，并且为了安全性考虑，不允许用户变更上级目录。通过此HOOK事件的引入，进一步完善了文件上传的功能，增强了系统的灵活性与适配性，为后续的扩展和应用提供了更高的可操作性。
6、在使用xc_hook_ftp发起文件上传请求时，系统会首先对上传文件进行严格的权限验证。验证流程具体如下：首先，系统通过file_exists函数检查本地待上传文件的存在性。如果文件不存在或缺失，将立即返回错误信息：“上传失败：本地文件不存在”。接下来，系统尝试通过xc_appkey_ftp_config读取关键的key参数，如果读取失败，则会返回错误信息：“上传失败：应用场景配置不存在”。最后，系统会检测remote_file文件是否位于允许操作的目录中，若目录不支持或用户无相关权限，同样会返回相应的错误信息。这一系列步骤确保上传过程的安全性和合规性。
7、在xc_hook_ftp模块中，采用了标准的宫论数组结构进行返回处理，以确保返回结果能够被HOOK钩子正确识别并进行响应操作。返回结果包含两个固定变量：code和msg。code用于指示返回处理的状态，若code为1，则表示处理失败。失败的原因可能多种多样，包括权限不足、未开启功能、文件缺失或上传接口异常等。具体的失败原因可以通过msg变量来获取。若code为0，则表示处理成功，文件已经成功云同步至指定服务器。无论如何，只要有code变量，便可以明确文件处理的状态。
8、为了更好地维护FTP和SFTP服务器，xc_appkey_sftp_config账户配置组将同时支持这两种服务器的账户信息配置。具体参数如下：首先，name用于说明账户的用途和场景来源，提供备注信息以便清晰了解账户的作用。其次，key作为唯一标识，在匹配和执行过程中需要通过这个参数来确认身份。ip则是指定FTP或SFTP服务器的地址。user和pass分别是服务器FTP或SFTP的登录账户名和密码，用于验证用户身份。port参数指定服务器的请求端口，而path则是上传目录，根据具体厂商的配置进行填写。type支持FTP和SFTP两种协议，确保上传协议的灵活性。最后，open参数用于指示接口是否启用，若关闭，则代表该接口已弃用。通过这些详细的配置参数，系统能够更加有效地管理和维护FTP及SFTP服务器，确保数据传输的安全性和可靠性。
9、在使用xc_hook_ftp发起文件上传时，系统会依次执行一系列检测步骤。首先，通过qf_get_option函数读取后台账户的配置信息，即xc_appkey_ftp_config，并将返回的数组存储到config变量中。接着，系统会利用xc_is_coinfig函数匹配与KEY一致的子数组配置信息。如果未能成功提取该信息，系统将返回错误提示：“上传失败：FTP应用场景配置不存在”。如果提取成功，系统会继续检测type协议是否为FTP协议；如果协议类型不匹配，则返回错误提示：“上传失败：场景不是指派FTP协议”。最后一步，通过empty函数检查【open】状态是否为开启状态；如果未开启，则返回错误提示：“上传失败：FTP应用场景已被管理员关闭”。只有在以上三个检测步骤全部通过后，系统才会进入文件上传的具体业务逻辑。
10、一旦账户信息参数获取，则xc_hook_ftp会尝试与远程服务器进行请求连接。具体处理过程如下：1、通过$config['ip']服务器IP地址和$config['port']对应端口号发起ftp_connect链接请求，并将连接对象保存到conn_id，如果链接失败则返回错误：上传失败：无法连接到FTP服务器。如果连接成功，则尝试通过$conn_id, $config['user'], $config['pass']：链接对象、服务器账户、服务器密码三个参数发起ftp_login登录请求。并将登录结果保存到login_result。如果登录失败则返回错误：上传失败：无法通过凭据连接到FTP服务器。如果登录成功则进行下一步操作。
11、通过 xc_hook_ftp 成功登录远程 FTP 服务器后（即获取到 login_result 登录对象的情况下），首先会调用 ftp_pasv($conn_id, true) 将服务器的模式切换为被动模式。这一操作是出于兼容性和保护性的考虑，因为部分 FTP 服务器仅支持被动模式的请求。随后，使用 ftp_put 发起文件上传请求。具体流程如下：首先获取 conn_id（即初始化的 FTP 连接对象参数），然后指定 remote_file（远程服务器上目标文件的保存路径）和 local_file（本地待上传文件的路径）。上传过程中设置传输模式为 FTP_BINARY，以确保文件以二进制模式传输，从而避免因文件类型被篡改导致上传后的文件无法正常识别的问题。如果上传操作失败，则会返回错误信息【上传失败：无法上传文件】。

2025年5月26日
1、宫论服务器在【PHP8.31】版本中新增了对FTP和FTPS扩展的支持，这一升级为服务器在数据传输方面提供了更多的灵活性。在此基础上，除了现有的SFTP（基于SSH协议）的数据传输方式外，服务器在执行异地容灾备份和指定文件同步发送等任务时，FTP协议也将成为一种可选的数据传输方案。这不仅丰富了数据传输的方式，也为用户在处理不同的网络环境和安全需求时提供了更多的选择和便利。通过这种扩展支持，宫论服务器进一步提升了其在数据管理和传输上的效率和适应性，后续数据同步的选择方案将更多。
2、xc_hook_sftp现已优化为通过try-catch机制捕获异常，确保在异常情况下不会错误返回。整个钩子的执行流程已被完整封装，具体步骤如下：首先，使用file_exists函数检测待上传文件是否存在，若不存在则立即返回错误信息。接着，读取关键配置以确认场景配置是否存在，若缺失则返回错误；若配置存在，则检查协议选择是否为FTP，若不是则返回相应的错误提示。在确认配置后，读取场景的其他配置，通过ftp_connect函数构建上传请求，若在构建过程中发生异常，将返回相应的错误信息。随后，调用$sftp->put方法执行上传请求，并监控返回结果，若发生错误则返回对应的错误信息。最后，上传请求成功完成后返回code=0，并通过ftp_close函数关闭上传接口。
3、在xc_hook_sftp中新增了一个关键变量：key。该变量在文件传输请求执行前必须主动提供，并且是读取的必要参数。它对应于后台配置中的【xc_appkey_sftp_config】组。系统会在进行文件传输请求之前，通过xc_get_option函数读取该配置，并将返回的数组存储在sftp_config变量中。随后，系统会对该数组进行解析处理，通过key来匹配相应的账户配置信息。如果配置读取失败，系统会立即返回错误信息【上传失败：SFTP应用场景配置不存在】。为了确保传输过程的安全性，所有的传输请求都必须通过后台配置来匹配相应的账户信息。
4、在成功从后台读取到账户配置信息后，会将返回的数组信息保存到config数组中，以确保后续的事件能够顺利进行所需的业务处理。若通过empty验证发现config数组为空，则会返回错误信息“上传失败：SFTP应用场景配置不存在”，提示用户当前没有配置相关信息以供使用。若config数组不为空，则会进一步检查其中的$config['type']是否为sftp协议。若检测结果显示不是sftp协议，则将返回错误信息“上传失败：场景不是指派SFTP协议”，表明该操作仅支持SFTP协议的场景。需要注意的是，xc_hook_sftp功能仅支持SFTP协议，若需要使用FTP协议，则此功能无法满足需求。
5、在xc_appkey_sftp_config账户配置组中，新增了一个名为“open”的布尔值字段，默认状态为true，即开启状态。该字段的主要功能是控制账户的传输协议启用情况。如果该字段被设置为false，那么当通过xc_hook_sftp发起文件传输请求时，将会收到错误提示：“上传失败：SFTP应用场景已被管理员关闭”。此变量的增加旨在提升账户配置的灵活性，使得在某些特殊情况下，只需在后台简单地将该字段设置为false，即可暂时停用相关账户，而无需彻底删除账户，从而保留了账户信息以便于未来的恢复和使用。
6、xc_hook_sftp文件上传HOOK脚本新增了一个可选变量：remote_file。默认情况下，该变量不需要传递，系统会自动读取后台的配置目录进行操作。然而，如果传递了该变量，则表示不需要使用后台指定的目录，而是将文件同步到指定的路径。系统会通过empty函数来判断remote_file是否被传递，如果传递了，系统将通过pathinfo函数读取本地待上传文件的信息，并将本地文件名称与远程目录进行拼接处理，确保文件上传到指定的路径。实际的路径地址参数为：【$remote_file . '/' . $file_info['basename']】
7、宫论项目正式部署【phpseclib3：基于 SSH2 的安全文件传输协议】，通过composer安装部署到当前项目SDK扩展中。在执行xc_hook_sftp方法进行文件上传请求的时候，系统会通过require_once加载【xc_sdk_composer】来集成该库到当前运行环境中，一旦完成了所有的参数效验后，执行脚本会使用内置的方法，new phpseclib3\Net\SFTP来构建一个SFTP对象，然后使用后台预设的账户端口等信息执行链接登录请求，一旦登录成功，则会尝试将指定文件传输到远程SFTP服务器中进行存储。
8、SFTP传输协议，具体的执行流程如下：1、首先加载phpseclib内置SDK库，通过xc_sdk_composer来集成部署。2、读取KEY并进行解析，获取到本次服务器的账户信息（IP、账户、密码、端口号）。3、调用phpseclib来生成一个SFTP对象参数信息。4、通过$sftp->login进行连接并登录到远程服务器，登录所需参数由KEY解析获取。5、读取本地文件，并调用$sftp->put方法发起上传请求，上传过程中需要两个参数本地文件，远程存储文件路径。6、发起上传请求，在传输完成后，执行关闭处理。防止内存泄露。
9、通过phpseclib3发起SFTP协议请求的时候，会通过try-catch来监听捕获异常错误。如果在构建sftp对象的时候发生错误、通过$sftp->login发起链接登录请求发生错误、使用$sftp->put发起文件上传请求发生错误。都会触发catch错误返回，此时会拦截并返回对应的错误信息，然后记录如下信息。上传时间、上传KEY参数、上传本地文件地址、上传人、错误信息。以日志的形式写入到【sftp_error】log中。日志通过宫论方法xc_log_error_warn($key, $log)执行写入。
10、通过使用 xc_hook_sftp 成功将本地文件同步至 SFTP 服务器时，会激活 Redis 计数器。该计数器的标识为：sftp_upload，用于记录 SFTP 文件同步的数量。用户可以通过 get_redis_count($key) 函数来获取详细的统计信息，支持多维度的数据分析，包括查询总数、今日、昨日、本周、上周、本月、上月、今年和去年等。值得注意的是，只有在文件处理成功的情况下才会触发计数器，如果在同步过程中出现 try-catch 错误，则计数器不会被触发。设置该计数器的目的是为了有效统计 SFTP 服务器的文件同步处理数量，帮助进行全面的数据分析和监控。
11、xc_hook_sftp模块已经完成封装处理，其执行流程大致如下：首先，系统读取后台的配置信息，并与提供的密钥参数进行验证，以获取相应的服务器账户信息。如果读取失败或账户已被停用，系统将返回错误信息。接下来，系统尝试读取本地文件local_file，如果文件不存在或者用户无权操作该文件，同样返回错误信息。随后，系统利用phpseclib3库构建SFTP请求，尝试登录并发起文件上传。在此过程中，如果发生任何错误，系统将返回相应的错误信息，并通过日志记录详细的错误原因。如果文件上传成功，系统通过Redis执行计数器操作，返回code=0表示成功，最后关闭SFTP对象以释放资源。

2025年5月23日
1、通过 xc_cloud_upload 发起云端同步请求时，如果传递的 update['sort'] 值为 local，则表示需要同步本地文件。此时，系统会首先执行 file_exists(update['local']) 来验证本地文件是否存在。如果文件不存在，将立即返回错误信息：“上传失败：本地文件不存在！”。如果文件存在，系统将继续读取 xc_upload_cloud_sort 配置，并根据配置执行相应的 SDK 上传操作。然而，由于此过程并未传递媒体库 ID，因此不会通过 xc_update_sql 执行回调动作。在上传成功后，系统会直接返回上传文件的 URL 地址信息。
2、在通过云端同步脚本进行远程文件上传时，如果update['sort']的值为local，那么成功上传后将执行一系列业务逻辑。首先，会检测delete变量是否存在且不为空。如果满足条件，则会主动发起删除请求，以清理本次上传的本地文件。接着，读取本地文件以获取其大小，然后通过update_redis_sorted_set进行计数统计。该过程会获取当天的时间戳作为成员，更新有序集合，以统计每日文件上传的总大小。注：因为local不会触发回调动作，因此需要再函数内执行一些上传成功的回调业务处理。
3、在上传本地文件到云端同步，除了会统计文件的upload_size的大小到有序集合以及外，还会通过内置方法mime_content_type来获取文件的MIME 类型，并将结果保存的变量mime中，然后调用xc_redis_count计数器，来记录upload_$mime，该计数器会这自动统计平台[图片=image 视频=video voice=声音]等上传成功次数，后续可以通过get_redis_count($key)来获取详细的统计信息，支持查询【总数、今日、昨日、本周、上周、本月、上月、今年、去年】等多维度的数据分析。
4、在成功获取到MIME文件类型后，这里会进行一个至关重要的处理。首先，通过xc_is_login方法获取当前登录用户，并将结果保存到user_id中。如果用户已登录，则会进行以下操作：如果MIME类型等于image，则通过xc_user_daily_hook方法发起一个计数统计，增加当前用户的upload_image图片上传次数；如果MIME类型等于video，则同样通过xc_user_daily_hook方法统计用户的upload_video视频上传次数。系统还设置了一个API接口拦截器，负责监控每日用户的视频和图片上传次数。即使用户通过云端发起上传操作，也要进行相应的计数统计，以防止用户超过上传限制。
5、在云端文件同步上传事件中，涉及到的计数器统计回调处理，仅限于非媒体库【ID】的云端请求。在执行时，系统会验证update数组变量是否存在ID字段，如果存在则跳过处理。这是因为在媒体库同步的业务逻辑中，已经有自己的一套标准进行计数处理和缓存更新处理，不需要重复性的计数操作。如果强制执行，可能会导致计数器重复触发，从而引起统计数值不准确的问题。注：local和url两个上传类型才允许触发（必须在文件确定同步成功后执行）
6、后台云端上传类型配置字段：xc_upload_cloud_sort，新增了一个上传场景【SFTP】。系统在同步上传文件到云端时，如果选择了SFTP，则会使用SFTP协议将本地文件上传到远程服务器。之所以采用SFTP，是因为大多数服务器都是Linux类型，使用SFTP进行传输更加安全可靠。相比之下，FTP协议不仅安全性较低，还需要额外安装对应的客户端。注：使用SFTP进行协议同步云端文件同步，本质上就是建立一个存储服务器，专门存储服务器对应文件。所有的本地文件都将通过这台服务器进行分发处理。
7、在后台appkey账户信息配置页，新增了一个名为【xc_appkey_sftp_config】的SFTP账户权限配置列表。该列表包含以下字段：name（账户说明）、key（IP或域名链接，即FTP或SFTP的服务器地址）、user（登录账户，即服务器FTP登录账户名）、pass（登录密码）和port（端口号，即服务器FTP请求端口）。服务器的参数配置通过后台进行管理，如果需要追加服务器或变更服务器参数，只需在后台修改对应数值即可完成。这一改进将大大提高后期维护的便捷性。
8、新增的钩子函数 xc_hook_sftp() 通过 SFTP 协议将本地文件上传到远程服务器。使用该函数时，需要提供三个必要的变量参数。首先是 key，它用于匹配 SFTP 配置的唯一键，这是在后台配置场景中设置的独特值。其次是 local_file，即本地文件的路径。需要注意，此处仅支持服务器上的文件同步功能，不支持远程文件的处理。最后一个参数是 $remote_file，它表示远程保存文件的路径，包括具体目录和文件名。值得特别指出的是，无论是本地文件路径还是远程存储位置，都必须设置为绝对路径，以确保文件能够正确地进行传输和存储。
9、在xc_appkey_sftp_config配置中新增了两个字段。首先是“path”字段，用于指定上传目录。该字段可以为空，根据具体应用场景进行配置。当设置了这个字段后，所有属于该场景的文件必须上传至指定的目录，以确保文件管理的规范性和安全性，避免因文件乱放而引发的混乱和风险。其次是“type”字段，用于指定上传协议类型。该字段的值固定为FTP或SFTP两种协议类型，并且两种协议共用同一份配置。在调用相应场景的上传接口时，系统会检测实际使用的协议是否与配置中的协议一致，如果不一致则会返回协议错误。这一新增配置旨在进一步规范上传流程，提高文件传输的安全性和一致性。
10、xc_hook_sftp上传接口已完成封装，该钩子返回标准的数组结构：code=0代表上传成功，code=1代表上传失败，msg是失败的详细原因。执行流程如下：1、通过require_once引入SDK组件，确保SFTP协议能够被支持。2、使用file_exists检测需要上传的文件是否存在，如果不存在直接返回错误。3、读取key检测是否场景配置是否存在，不存在返回错误。配置存在则检测协议选择是否为sftp，不是也返回对应错误。4、读取场景其他配置，通过new phpseclib3\Net\SFTP构建上传请求，如果构建过程出现异常，返回对应的错误。5、调用$sftp->put执行上传请求，并且监听返回，如果错误返回对应信息。6、完成上传请求，返回code=0。
11、对SFTP上传接口进行了优化：首先，在后台新增了一个名为$config['open']的字段，用于判断当前场景是否被临时弃用。如果该字段被设置为关闭状态，当用户尝试上传文件时，系统将直接返回一个错误信息【上传失败：SFTP应用场景已被管理员关闭】。这一措施有效地防止在不适宜的情况下继续进行上传操作，从而保证系统的稳定性和安全性。其次，在整个上传流程中引入了try-catch机制来捕获异常事件。通过这种方式，如果在执行过程中出现任何异常，系统将立即返回相应的错误信息，从而避免上传过程中出现错误导致整体返回结果的不一致性或失败。

2025年5月22日
1、在成功读取到xc_upload_cloud_sort配置参数后，xc_cloud_upload方法会立即通过require_once加载配置中指定的【xc_get_option('xc_sdk_composer')】文件，以便将宫论项目的所有SDK集成到当前环境中。随后，该方法会根据后台返回的配置参数发起相应的上传请求。目前，该功能主要集成了腾讯云对象存储（COS），因此在加载完相关SDK后，会调用Qcloud\Cos\Client类来发起COS云文件同步请求，并将处理结果存储在cosClient对象中。
2、通过xc_cloud_upload发起宫论媒体库资源上传同步请求时，会对原有的资源进行状态检测，如果state等于delete，则返回错误【上传失败：文件已被删除!】，如果$upload['state']等于ok，则返回上传失败，文件已完成上传。并使用parse_url对本地的链接进行解析处理，如果$parts['scheme']不存在，则说明存在域名节后，此时会提示错误：上传失败：等待上传的文件是远程地址。注：通过上述验证，防止出现重复执行上传，或者已删除的媒体库资源发起上传请求。
3、在成功地处理了本地文件的读取后（通过file_exists函数验证文件是否存在，如果文件不存在，将返回相应的错误信息），接下来需要读取与“宫论”相关的后台云端账户配置信息。这些信息包括但不限于腾讯云账户的SecretId（即xc_tencent_secret_id）、腾讯云秘钥的SecretKey（即xc_tencent_secret_key）、存储桶的地域（即xc_upload_cos_region）、存储桶的名称（即xc_upload_cos_bucket）、以及cos的自定义域名（即xc_upload_cos_domain）等。这些参数的提取和封装是为后续上传SDK的调用做好准备工作，确保上传操作能够顺利进行。
4、通过xc_cloud_upload发起云端同步请求，如果同步的类型为（媒体库ID）并且SDK类型为cos对象存储，那么它的处理逻辑如下：1、使用new Qcloud\Cos\Client构建上传行为，将之前封装好的腾讯云账户信息写入到对应对象中，然后将body对象设置为$upload['local']，请求将该文件进行上传处理，对应的key（存储的路径地址和文件名称）则读取$upload['remote']参数。最后调用$cosClient->upload方法进行上传请求。注：验签过程会在cosClient对象中进行，这里不需要进行任何处理。
5、通过cos发起云端同步请求的时候，为了确保执行的安全可靠性。会采用try-catch来捕获错误和异常，确保上传中出现的任何异常错误都可以被定位到，也是确保返回的结构体使用是标准数组结构，不会因为SDK的返回为对象或者其他参数，造成返回结构不被系统识别。具体的处理方式如下，try负责执行$cosClient->upload上传请求行为，果过程中发生任何错误，如文件损坏、权限不足、接口异常或账户欠费等，catch块则会捕获异常并进行相应的处理，通过catch(\Exceptione)来转发和记录这些错误信息，确保系统能够稳定地处理各种异常情况。
6、通过云端同步接口发起cos上传请求时，如果cos_result执行返回上传成功。会主动检测请求方式是否为ID，如果是ID则表明本次是和宫论数据表xc_upload进行关联的，此时在返回结果前，会进行xc_update_sql回调操作，主要对两个字段进行更新处理。1、remote：远程CDN地址，上传成功后会进行封装【xc_get_option('xc_upload_cos_domain') . '/' . $upload['remote']】结构为CDN域名+KEY键名方式拼接。2、state：将数据表的状态标记为OK。表明该媒体库ID已完成云端同步工作。
7、在完成云端资源的同步操作后，对于使用ID作为主键的同步类型，会触发文件上传成功的回调动作：xc_upload_hook_success。该钩子专门用于处理业务回调操作，任何成功上传到宫论媒体库的资源都会激活此钩子，确保系统内置的方法能够准确监听到上传行为。同样的处理也适用于云端同步。只要确认上传成功，就将ID传递给这个回调动作，由其负责后续的执行。后续的业务逻辑则不在此处进行处理。
8、在云端文件成功同步至COS对象存储桶后，除了触发通用的回调动作事件外，还会通过xc_do_action注册动作钩子，以便进行业务回调操作。在注册过程中，会传递一个固定的参数ID作为身份标识，允许第三方通过注册方法挂载回调方法，从而接收此次回调的通知。完成上述操作后，COS版本的云端上传业务即宣告完成。此时，系统会返回四个字段：code=0表示本次同步成功；msg为“文件云端同步成功”；type指示同步方式为腾讯云对象存储（COS）；url则为封装并拼接好的CDN地址，供直接访问使用。
9、通过cos上传同步远端对象的时候，如果触发catch错误监听，则会触发一个日志报警器。日志的标识为：cloud_upload，日志的记录结构为【[上传时间: - ' . date("Y-m-d H:i:s") . '] [上传用户: - ' . $upload['user_id'] . '] [错误日志: - ' . $e . ']】记录动作是通过调用xc_log_error_warn方法来完成的。需要注意的是，这条日志记录仅用于错误追踪和分析，不会触发任何报警机制。只要上传过程中发生的任何错误，都会触发这个日志写入，具体错误原因为$e变量提供。
10、增加了一个名为“cloud_upload”的Redis计数器，用于记录xc_cloud_upload方法在处理云端文件时的执行成功次数。无论文件是通过何种同步方式上传、使用哪种存储机制，只要通过xc_cloud_upload方法成功上传文件，便会触发xc_redis_count脚本进行计数处理。后续可以通过get_redis_count($key)来获取详细的统计信息，支持查询【总数、今日、昨日、本周、上周、本月、上月、今年、去年】等多维度的数据分析。
11、在云端文件同步成功后，系统会对传递的变量upload数组进行检查，以确认是否存在【delete字段】。如果该字段存在且不为空，脚本将执行删除本地文件的操作。通常，delete参数用于标记临时文件，例如远程下载的图片，这些文件会被保存到临时目录中。一旦同步到云端，便需要立即进行清理，因为这些临时文件在后续操作中已不再需要。如果不及时清理，可能会导致服务器磁盘空间的浪费。完成delete字段的检测和处理后，整个cos对象的远程同步工作便告一段落。通过这种机制，确保了服务器资源的高效利用和管理。

2025年5月21日
1、在执行xc_upload_thumbnail_save方法时，如果需要将缩略图上传至云端，该方法会内部调用xc_cos_upload方法。此方法是一个封装好的SDK上传请求，用于处理所有cos文件的同步请求，以便于后期的维护和管理。为了确保上传过程的顺利进行，xc_cos_upload方法需要接收两个变量参数。首先，$url参数可以是本地图片或远程图片，但目前尚未兼容base64格式。其次，#name参数用于指定上传的保存位置，若无需指定则可以留空。通过这种设计，确保了上传过程的灵活性和高效性。
2、对xc_cos_upload作为宫论云端文件同步方法进行了优化升级，以确保其能够适应所有场景，并成功接入宫论的媒体系统。首先，对云同步功能进行了调整，采用标准化的数组结构来返回结果。其中，code=0表示文件上传并同步成功，code=1则表示上传失败。上传失败的原因可能多种多样，需要通过msg字段来获取具体的错误信息。如果上传成功，还会返回一个额外字段：cdn，即远程可直接访问的文件路径地址。
3、考虑到兼容性问题，直接修改 xc_cos_upload 方法的业务逻辑可能会对已经集成的上传场景产生影响。因此，我们决定重新封装一个新的方法来进行适配处理，而原有的 xc_cos_upload 方法将被恢复至其初始状态，不做任何改动。那些已经使用 xc_cos_upload 方法的场景将在后续逐步迁移到新的方法上。新的方法命名为 xc_cloud_upload，其中“cloud”表示云端同步的意思。该方法不仅限于 COS（对象存储服务），未来还将集成更多的同步方案，如存储服务器备份、OSS（对象存储服务）等，以提供更广泛的支持和灵活性。
4、在后台上传配置页面们新增了一个参数字段：xc_upload_cloud_sort【上传类型】。目前，这个上传类型是一个单选项，只有一个选项可供选择，即【cos：腾讯云对象存储】。在同步云端图片数据时，系统将根据这个上传类型读取相应的设置，并调用对应的SDK发起上传请求。这一参数匹配的设计，旨在为未来的扩展性做好准备。随着云端同步方案的不断发展，我们计划提供更灵活的选择，包括【本地、备用服务器、cos、oss】等选项。通过这种适配处理，用户将能够轻松一键切换不同的上传类型，极大地提升了系统的灵活性和适应性。
5、xc_cloud_upload方法现在对url变量的处理不仅支持url图片，还增加了对宫论媒体库ID的支持。如果传入的是url链接资源，将通过xc_local_is方法进行参数验证和解析。如果验证结果显示资源为本地资源，则返回服务器的真实路径，通过内网数据处理并执行上传请求。如果is_numeric函数返回true，则表明传递的参数是数字类型，此时将通过xc_query_upload方法发起订单查询，通过ID检索对应记录的存在性。如果记录不存在，将返回code=1，表示媒体库资源查找失败；如果记录存在，则会将查询结果赋值到upload数组中。
6、对xc_cloud_upload方法的变量参数结构进行了优化，以提升其高扩展性。优化后，该方法不再接受固定的变量参数，而是改为通过数组结构进行传参处理。在调用此方法时，需传递一个名为【upload】的数组。该数组中必备的参数包括：id（对应宫论媒体库的主键ID值）和key（表示文件的路径及名称，例如XXX/xxxx/22.jpg），文件将会以此名称进行云端同步上传。此外，还可以选择性地传递参数type，用于指定上传的类型和来源。通过这种数组方式传递参数，当未来需要对参数进行变动或调整时，将会更加灵活和便捷。
7、upload数组变量新增了三个字段参数：首先是url字段，该字段用于传递远程图片或本地图片的地址，以便在需要进行云端同步时使用。其次是sort字段，该字段的固定值为"url"或"id"，用于区分当前同步的文件是媒体库类型还是链接类型。最后是delete字段，这是一个布尔值，默认为false。当进行本地文件上传时，如果将delete标记为true，则在文件成功同步到云端后会主动删除本地图片。通常情况下不建议开启此功能，以避免误删文件，但对于临时文件的处理可以考虑启用。
8、在通过xc_cloud_upload发起云端参数同步时，系统首先会检查upload数组是否为空。如果该数组为空，则会立即返回错误信息：“同步失败：数组参数不能为空”。如果upload数组不为空，系统会进一步验证【key、type】两个参数是否已提供，这两个参数是必传项。如果其中任何一个缺失，将返回错误信息：“同步失败：必备参数缺失无法上传”。在确保所有必需参数存在后，系统会根据type参数的值进行进一步的验证。如果type的值为id，系统将检查数组中是否包含有效的ID。如果ID缺失或为空，系统会返回错误：“同步失败：媒体库主键不存在”。如果type的值为url，系统则会验证数组中是否包含有效的URL。如果URL缺失或为空，系统会返回错误：“同步失败：URL参数不能为空”。这些步骤确保在上传过程中所有必要的信息都得到正确处理，以避免数据同步失败。
9、如果所需的所有核心参数都存在，则会进行进一步的核验处理：首先，通过is_numeric函数验证ID是否为数字，如果验证失败，则返回错误【同步失败：媒体库资源查找失败】。其次，通过xc_local_is函数验证传递的url参数是否为本地路径，如果验证失败，则返回错误【同步失败：不是有效的link地址】。最后，检测url是否为外部链接，如果是外部链接，则会尝试通过内置的宫论接口去检测文件的可访问性，如果文件不可访问，则返回错误【同步失败：远程图片不可访问】。
10、通过xc_cloud_upload发起云端资源同步，最核心的环节在于确保文件位于服务器本地。在执行函数前会初始化一个变量local_file，其默认值为空。如果通过媒体ID读取文件，则会使用字段【local】，该字段包含本地文件的绝对路径，并通过宫论API接口上传文件，这种情况下本地文件路径必定存在。如果文件通过URL提供，则会使用xc_local_is函数获取其本地绝对路径。如果文件位于远程服务器，则会先将其下载至本地，并返回临时路径。所有这些处理逻辑的最终目的是获取local_file地址，以便进行后续操作。
11、local_file如果不为空，则表明系统已成功获取到本地文件。此时，系统会通过file_exists函数来验证该文件是否确实存在。如果文件不存在，系统将返回错误提示【同步失败：本地文件读取失败】。若文件存在，系统会继续读取xc_upload_cloud_sort配置字段，以确定所需的同步方式。系统具备高度灵活性，支持多种云端同步方式，并根据配置调用相应的SDK接口（每种云端同步方式所使用的SDK各不相同），从而进入文件的云同步上传流程。

2025年5月20日
1、在执行数据表更新的过程中，xc_update_sql_callback会通过Redis触发计数器统计，标识为：update_sql_callback。此计数器记录数据表更新动作的触发次数，后续可通过get_redis_count($key)获取详细统计信息。该功能支持多维度查询统计，包括总数、今日、昨日、本周、上周、本月、上月、今年及去年等时间维度，方便全面了解数据表更新的频率和趋势。此外，计数器具备监听每日SQL更新调用次数的能力，为数据管理提供了精准的监控工具。
2、xc_update_sql_callback方法进一步扩展处理，加入了日志记录功能。当通过该方法执行缓存清理动作时，支持通过日志记录错误返回。具体操作流程如下：首先，通过内置的统一查询方法获取本次更新的数据表记录。如果获取成功，则根据数据表类型执行相应的缓存更新或其他操作。如果执行失败，则记录当前时间日期、执行用户、执行场景、执行主键ID、以及返回的错误信息到【update_sql】日志文件中。这一功能的加入将大大方便后续运维人员进行跟进和查询处理。
3、在缓存更新场景中，不仅需要关注数据表更新时触发的操作，还必须处理数据表行被删除时的情况。因此，为了确保缓存的准确性，在xc_delete_sql事件中也集成了xc_update_sql_callback方法。这样一来，当系统通过这个方法执行SQL操作删除指定行时，相关的SQL回调动作将会被自动触发，从而主动清理对应的缓存。这种机制有效地避免了数据表删除后由于缓存残留导致前后端查询仍返回过时数据的问题，确保数据的一致性和实时性。
4、xc_update_sql_callback进行了升级优化处理，现在支持xc_do_action(FUNCTION, $result, func_get_args())【宫论动态注册钩子】功能。当通过add_action注册回调函数时，系统会在处理缓存结构后，自动调用并触发预设的方法。此次回调将包含两个变量【table_name：数据表名、id：对应的主键ID值】，这些变量会被发送到注册的方法中，允许在该方法内执行相应的业务逻辑。例如，可以主动清理自己挂载的缓存参数，以确保系统的缓存数据始终保持最新状态。
5、针对SQL更新操作，由于可能会被外部第三方事件挂载一些复杂的方法，这些业务逻辑有可能阻塞整个进程的执行。为了解决这一问题，在执行xc_update_sql_callback操作时，现在统一采用Swoole框架进行处理。通过异步方式处理，可以有效地响应缓存的更新以及附属业务的执行。在具体执行方法时，我们使用xc_is_swoole方法来验证当前是否处于异步状态。如果未处于异步状态，则将操作转发到异步进程进行响应处理；如果已经处于异步状态，则跳过验证，直接进行执行。这种策略优化了系统的响应速度和处理效率，确保业务逻辑的顺畅执行，同时避免了可能的阻塞问题。
6、在 xc_update_sql_callback 函数中新增了一个名为 action 的第三个变量，该变量的默认值为 update，可选值为 delete。当 action 的值为 update 时，表示此次触发是由于数据表的更新操作，此时需要做的就是更新相应的缓存，而无需进行复杂的处理逻辑。而当 action 的值为 delete 时，意味着此次操作是由 xc_delete_sql 触发的删除动作，系统要求删除该记录的所有缓存，而不是执行更新操作。在这种情况下，处理逻辑与更新操作存在显著差异，需要根据 action 的值来决定采用何种业务处理方式，以确保系统正确执行相应的操作。
7、通过宫论封装的方法执行SQL操作时，系统会在操作成功后自动触发相应的callback回调动作。这些回调动作通常用于更新缓存、同步缓存或删除缓存，以确保数据的一致性和可靠性。回调挂载的机制采用统一查询接口设计，只要SQL发生变动，系统会主动更新统一查询方法的缓存，从而保证查询结果的实时性和准确性。此外，该回调机制支持第三方挂载，允许外部注册自定义方法以接收和处理更新事件，进一步增强了系统的扩展性。同时，系统集成了日志记录功能，详细记录每次回调的触发情况，便于运维人员实时监控和排查问题，全面提升了系统的可维护性和稳定性。
8、为了确保宫论中的所有SQL操作能够准确有效地触发xc_update_sql_callback事件，不仅在xc_update_sql和xc_delete_sql方法中集成了该事件，还将其整合到了xc_insert_sql方法中。当通过内置方法生成SQL语句时，系统会主动触发回调，并将action标记为insert插入。如此一来，无论是数据库的统一插入函数、统一修改函数还是统一删除函数，都能够在执行过程中准确有效地执行回调功能。这种设计保证了数据库操作的一致性和可靠性，确保在每次操作时都能顺利触发相应的事件处理机制。
9、新增了一个定时任务计划：xc_task_thumbnail_clear()。该方法无需传递任何参数变量。具体执行时，该方法会主动读取位于 $_SERVER['DOCUMENT_ROOT'] . '/cache/image/temporary/' 的缩略图临时目录文件。如果该目录存在且其中包含临时缩略图图片，则会触发清理函数【xc_delete_path】，请求系统对该目录进行清理操作。由于上传操作的原因，在生成缩略图时，系统会在指定目录中创建一个临时缩略图文件。
10、在后台定时计划配置组中新增了一个固定计划任务，旨在每隔三天自动触发一次，以高效清理服务器上的缩略图临时文件。该任务被命名为“清理缩略图临时文件图片”，其核心功能由函数“xc_task_thumbnail_clear”实现。为确保任务的顺利执行并避免对主进程造成阻塞，我们采用了Swoole技术进行请求转发，使其以异步方式运行。一旦计划生效，系统将定期扫描并清理temporary目录中的缩略图临时文件，防止随着时间的推移文件数量不断增加而占用服务器的磁盘空间。需要注意的是，这些临时文件不需要长期保留，定期清理有助于维持服务器的运行效率。
11、在xc_upload_thumbnail_save方法中，新增了一个名为Cloud的变量，默认值设定为false。当该变量被标记为true时，意味着此次生成的缩略图需要上传至云端，并同步至COS对象存储桶。在此情况下，内部方法将调用腾讯云SDK，发起文件上传请求，并确保上传文件的路径与服务器上的缩略图路径保持一致。如果上传操作成功，将额外返回一个名为【cos】的变量，该变量指向缩略图在CDN上的地址。若上传失败，则不会返回该字段，但本地生成的缩略图仍然会正常返回。

2025年5月19日
1、在处理动态缩略图的过程中，系统不仅会验证处理来源是否为图片类型（image），还会检查设置项xc_upload_thumbnail_open是否处于开启状态。如果该设置项被关闭，系统将跳过缩略图生成过程，并返回错误信息【处理失败：后台已关闭生成缩略图】。此设计旨在避免在后台关闭缩略图生成功能时，系统仍然通过xc_upload_thumbnail_save尝试生成缩略图，从而导致不必要的服务器性能消耗和磁盘空间占用。
2、通过xc_upload_thumbnail_save生成缩略图时，首先会读取原数据表的信息，检查其中是否包含【thumbnail】字段。如果该字段存在，系统会使用file_exists函数检测本地是否已有对应的缩略图文件。如果文件不存在，则表示缩略图可能已丢失或不可用，这时才会通过接口请求并生成新的缩略图。引入这个检测机制，旨在避免在数据表中已有缩略图记录的情况下，重复生成缩略图，从而节省系统性能。
3、新增了一个名为xc_query_upload的统一查询方法，专门用于检索宫论媒体库中的记录。此方法已经集成到【统一查询脚本：query.php】中，并且未来所有针对上传数据表的查询请求都将通过这个方法进行。使用该方法时，需要传递一个固定变量【id】，它对应于xc_upload数据表中的主键ID值。通过这个唯一标识，可以获取相应的媒体库信息。在构建查询请求时，系统会首先验证ID是否存在且为数字；如果验证未通过，则会立即返回false，终止后续的查询操作。
4、在构建xc_query_upload方法时，遵循与其他统一查询方法相似的逻辑流程。首先，通过引用全局变量【wpdb】对象，利用它来创建查询语句，以检索数据表中的【xc_upload】ID匹配的记录。为保证安全性，查询语句通过prepare方法进行参数过滤，从而有效防范SQL注入的风险。查询操作使用get_row方法，确保仅返回一条记录，并通过ARRAY_A选项强制结果以数组形式返回。若查询成功并存在结果，则返回对应的数组信息；若无匹配结果，则返回false。这种严谨的处理方式不仅提高了查询的安全性，还确保了数据返回的准确性和一致性。
5、为了提升系统的灵活性，在统一订单查询功能中引入了更为多样化的ID变量查询方式。除了传统的主键ID查询方法外，现在系统还支持通过CDN加速域名路径进行查询。当接收到一个查询请求时，系统会首先利用is_number函数判断传入的ID变量是否为纯数字或数字字符串。如果是数字字符串，系统将采用主键ID的方式构建查询语句进行数据检索。如果ID变量不是数字，系统将进一步检查该字符串是否包含域名信息。若检测到域名，系统会尝试匹配数据表中的【cdn】字段。一旦匹配成功，系统将按照标准处理流程返回相应的数组结构信息；如果匹配失败，系统则会返回false，提示查询未能成功匹配。通过这种多层次的判断与匹配机制，能够更加高效和准确地响应不同类型的查询请求。
6、在xc_query_upload功能中增加了一个用于缓存控制的开关变量uncache，默认值为false，以启用并优先返回Redis缓存的结果。在系统查询上传媒体库信息时，将会构建一个Redis键位："query_query:" . $id。若启用缓存查询，系统会通过get_redis_meta函数进行缓存查询；如果缓存记录存在，则直接返回缓存数据。如果缓存记录不存在，则系统会使用wpdb语句进行数据库查询，并将结果保存到Redis键位中，以便下次查询时能够直接读取缓存数据。此缓存的有效期设定为30天，考虑到上传记录的变动性较低，因此可以适当延长缓存时间，而无需像其他缓存查询那样保持24小时的实时性。
7、xc_query_upload的缓存刷新机制进行调整优化，因为查询变量ID是同时控制两个字段【1、ID主键，唯一值参数值。2、cdn：媒体文件的CDN加速域名路径】，因此在对缓存操作上的处理，需要同时兼顾上述两个查询结果，避免缓存更新的时候，只更新了其中一个，造成了查询到的缓存结果，与实际的数据表结果存在不一致的情况。具体优化方法为，在涉及redis处理更新的时候，会同时构建两个reidis键位，分别对应上，并同时执行操作。
8、完成统一订单查询【宫论上传媒体库】的方法封装，具体流程如下：1、初始化 Redis 缓存键：基于输入参数 $id 创建 Redis 缓存键 query_upload:<id>。2/检查 Redis 缓存： 如果 $uncache 为 false 且缓存存在： 如果缓存值为 'false'，返回 false（表示之前查询未找到数据）。 否则，返回缓存中的查询结果。3、构建 SQL 查询： 根据 $id 的类型： 如果是数字且长度不超过 8 位，使用 id 字段进行查询。 否则，使用 remote 字段进行查询。4、执行数据库查询： 使用 $wpdb->get_row() 执行 SQL 查询，获取结果。5、处理查询结果： 如果查询成功： 将结果缓存到 Redis，使用 id 和 remote 作为缓存键，设置缓存有效期为 86400 秒（1天）。 返回查询结果数组。 如果查询失败，返回 false。
9、对xc_upload_thumbnail_save方法进行了优化处理。由于已经集成了统一订单查询方法【xc_query_upload】，在生成缩略图时，读取媒体库信息不再使用wpdb构建查询语句，而是采用统一的查询方法。查询时，优先启用缓存机制，如果缓存中存在所需数据，则直接返回缓存结果；只有在缓存中找不到数据时，才会通过wpdb方法发起SQL请求进行处理。需要注意的是，后续所有涉及媒体库资源的查询调用请求都将升级为使用统一的【xc_query_upload】方法。
10、在xc_update_sql中新增了一个监听回调机制：此机制旨在统一管理数据表的修改变更操作，所有数据表在进行操作时（除wp系统自带表外）均需通过此方法发起处理请求。该机制允许接受一个回调方法，用于执行缓存清理和刷新操作。具体实施过程是：当xc_update_sql成功更新数据表记录后，会立即触发回调操作，记录此次操作的数据表名称及其主键ID。随后，将调用一个新封装的方法，该方法专门负责处理订单或记录的缓存需求，确保相关缓存能够得到及时更新和维护，从而提升系统的整体性能和响应速度。此改动不仅简化了缓存处理流程，还提升了数据变更的可控性和系统稳定性。
11、新增了一个名为 xc_update_sql_callback 的方法，用于在 SQL 更新后触发缓存刷新的事件处理。该事件会接收两个参数：1. table_name（数据表名），该参数始终包含 wp_ 的数据表前缀。如果缓存处理逻辑需要验证表名，需通过 $wpdb->prefix 检查表名前缀的合法性；2. id（数据表的主键 ID 值），此参数为唯一标识符。该方法通过 id 和 table_name 的组合来定位具体更新的行数据。在方法执行前，会进行必要的参数校验：首先检查 table_name 是否为已存在的合法数据表，若不存在则判定为非法请求；其次检查 id 是否为有效的数字类型，以确保数据的准确性和安全性。这一设计旨在提高缓存刷新操作的精准性和稳定性，同时避免因参数异常导致的潜在安全隐患或数据处理错误。

2025年5月16日
1、宫论上传接口的配置中心新增了一个字段：xc_upload_thumbnail_open，该字段用于设置是否开启上传图片时自动裁剪生成缩略图的功能。此功能为可选项，用户可以根据需求自行决定是否启用。当用户选择开启该功能时，系统将在上传图片时自动触发缩略图处理逻辑。通过内置的接口，系统会对上传的图片进行缩略图处理，并将处理后的缩略图保存至本地，同时同步至云端。这样一来，在后续调用时，系统能够自动检测是否存在对应的缩略图，并根据检测结果执行相应的业务逻辑，优化图片加载速度和用户体验。
2、在后台启用xc_upload_thumbnail_open功能后，页面将新增显示以下字段参数：首先是xc_upload_thumbnail_size，该参数用于设置缩略图尺寸的触发要求，以整数形式表示，单位为MB，并精确到小数点。例如，如果设置为0.1MB，则当图片小于100KB时不会触发缩略图处理，因为图片尺寸过小，无需生成缩略图。其次是xc_upload_thumbnail_directory，该参数指定缩略图的上传目录，所有接口生成的缩略图都会统一上传到这个目录进行存储。这样可以有效管理和存储缩略图，确保资源的合理利用和访问的便捷性。
3、在缩略图的配置方面，除了可以设置尺寸生成条件和目录外，还可以调整以下参数字段，以满足特定需求。首先，参数“xc_upload_thumbnail_mime”用于指定生成缩略图的格式，常见的格式包括jpg和png。建议根据实际需求进行选择，除非有特殊要求，否则尽量避免使用其他格式，以防止兼容性问题的出现。其次，参数“xc_upload_thumbnail_width”用于定义裁剪时的宽度要求。例如，如果设置为500px，缩略图的宽度将固定为500px，而高度则会根据比例进行自动适配。这种灵活的配置方式确保了缩略图在不同平台和设备上的良好显示效果。
4、在生成缩略图的过程中，为了实现更灵活的配置处理，引入了一个新的切换选项卡字段：xc_upload_thumbnail_type。这一字段包含两个选项，分别对应不同的裁剪策略。用户可以根据需求选择通过宽度或高度来适应裁剪，从而生成符合要求的缩略图。具体而言，如果选择“高度”作为裁剪依据，系统将展示xc_upload_thumbnail_height字段，用户可以在此填写所需的缩略图高度，随后宽度将自动调整以适应该高度。同样地，如果选择“宽度”作为裁剪依据，则会展示相应的宽度设置字段，系统将根据填写的宽度进行自适应处理，以确保缩略图的完整性和视觉效果。
5、在宫论数据表【xc_upload】中，我们新增了一个名为“thumbnail”的字段，用于存储缩略图地址。这个字段的类型设置为VARCHAR，最大长度为255字符。当系统生成缩略图后，会自动对其进行裁剪处理，以便在需要调用缩略图时进行展示。调用时，系统会优先检测媒体上传表中的thumbnail字段，若该字段不为空，则直接读取并展示对应的缩略图；若为空，则会通过其他方式进行处理。通常情况下，在发起上传请求时，缩略图会自动生成并保存，确保上传内容的高效处理和展示。
6、宫论通用上传脚本【upload.php】无论是通过H5、APP、网页还是小程序进行上传，均由该脚本负责处理文件上传操作。当前，该脚本具备监听image类型的功能，当图片上传请求完成后，会自动检测配置项xc_upload_thumbnail_open的状态。如果该配置项处于开启状态，脚本将读取此次上传的图片，并根据后台设置的参数，调用xc_imageManage_sdk进行缩略图处理。生成的缩略图会被移动至后台指定的目录，并将其路径保存到xc_upload数据表的thumbnail字段中，以便后续使用。这一流程确保了图片上传的高效管理与处理，提升了系统的灵活性与可扩展性。
7、在进行上传脚本的设计时，意识到直接在上传过程中处理缩略图可能会限制后续的调整和优化。考虑到可能会出现需要重新生成缩略图的场景，例如检测到缩略图缺失时自动生成，因此决定封装一个专门的方法来处理这些需求。我们创建了名为xc_upload_thumbnail_save()的方法，该方法的作用是接收【xc_upload】的主键ID，然后从数据库中读取相关数据，并将其保存到一个thumbnail数组中。这样设计的好处是后续所有与缩略图相关的操作都将集中在这个数组中进行，确保了处理的灵活性和可扩展性。通过这种方式，不仅提高了系统的稳定性，还为未来的功能扩展提供了便利。
8、现在xc_upload_thumbnail_save返回的标准数组结构，以便上级可以知道具体的处理结果。如果返回code=1，则代表处理失败，这个失败是多样的，一般有以下情况：文件读取失败，操作失败，保存失败，权限问题。数据表查找失败，数据表对象不存在，也会造成这个错误。需要根据msg去获取具体的错误原因。code=0则代表处理成功，这个处理成功是值得是，缩略图生成到指定文件，并且对应的数据表主键thumbnail完成了回调写入动作。
9、整个xc_upload_thumbnail_save方法的处理流程如下：首先通过xc_get_sql方法读取上传数据表的信息，如果读取失败则返回错误，目前该方法仅支持宫论媒体库文件来生成缩略图。然后获取到本地图片，并解析绝对路径。读取后台的具体配置参数（生成要求），然后通过xc_imageManage_sdk发起生成缩略图处理，如果发生错误，则将错误继承下来，并进行输出处理。如果生成成功，则读取临时缩略图，将图片移动到后台配置的目录，并将移动后的地址保存到数据表【通过：xc_update_sql进行数据表回调操作】，返回操作成功，结束整个生成动作。
10、通过xc_upload_thumbnail_save生成缩略图成功后，会立即执行两个动作（也可以理解为操作回调处理）1、首先会将xc_imageManage_sdk接口产生的临时图片，进行主动删除处理。2、通过redis发起计数器统计功能，统计标识为：upload_thumbnail，记录系统缩略图的生成次数。后续可以通过get_redis_count($key)来获取详细的统计信息，支持查询【总数、今日、昨日、本周、上周、本月、上月、今年、去年】等多维度的数据分析。
11、在宫论的上传接口（upload.php）中，当图片成功上传后，将触发xc_upload_hook_success($id)回调钩子，以启动【缩略图生成】的动作。具体操作包括读取上传文件的主键ID，然后利用Swoole发起异步执行请求，以生成该图片的缩略图。异步执行的函数是：xc_upload_thumbnail_save。需要特别注意的是，这里采用异步处理方式是为了避免阻塞进程，确保系统的高效运行。在异步处理缩略图的生成过程中，有效规避了因IO操作可能导致的各种意外情况，提高了整体系统的稳定性和响应速度。

2025年5月15日
1、在nginx配置自动缩略图功能之外，新增了一个内置处理脚本方法：xc_imageManage_sdk()。该方法专门用于对图片进行多种处理操作，考虑到实际应用场景中，图片的处理需求多种多样，比如格式转换、尺寸调整、质量压缩以及裁剪处理等。为了能够灵活应对不同的上传场景，决定将这些功能封装到一个扩展中，使得在后期使用时可以方便地直接调用。该方法默认依赖于imageManage组件进行处理，确保了处理过程的高效性和一致性。通过这种方式，不仅提升了系统的灵活性和可扩展性，也为开发人员提供了更为便捷的工具，以满足不断变化的业务需求。
2、xc_imageManage_sdk方法需要传递两个变量参数来进行图片的处理。第一个参数是image，即图片的地址，也就是需要处理的图片。当前该方法仅支持通过图片链接来传递图片参数，不支持直接传递图片对象。第二个参数是option，用于配置具体的处理操作。目前计划支持以下几种操作：首先，可以调整图像的尺寸，包括宽度和高度的修改，以满足不同的需求。其次，提供图像压缩功能，能够在保持图片原有尺寸规格的情况下进行压缩处理，压缩比可以在30%到100%之间调节。此外，还支持图片格式的转换处理，例如将PNG格式的图片转换为JPG格式。最后，针对某些上传场景中图片会自动横向旋转的问题，增加了旋转图片方向的功能，以便对图片进行复原处理。
3、在使用 xc_imageManage_sdk 对图片进行处理时，系统会对传入的 image 变量参数进行详细的检查和处理。当传递的是宫论域名时，程序会自动调用内置方法，将其转换为本地的绝对路径。例如， 链接 会被自动转换为 /www/wwwroot/www.acocoa.com/1.jpg。此功能仅支持宫论主域名的路径，并且会通过 xc_home 函数来验证域名信息的正确性。这样的处理方式有效地增强了 image 变量的扩展性和灵活性。
4、在调用内部SDK进行图片处理操作时，系统将返回一个标准化的数组结构，以确保后续处理能够及时响应并进行处理。当返回的code为0时，表示图片处理已成功完成。此时，根据传入的option参数，对原始图片进行进一步的扩展操作，后续的处理将由上层方法继续执行。若返回的code为1，则表示处理失败。失败的原因可能多种多样，包括文件不存在、权限不足、内部异常错误或方法调用错误等。具体的错误原因需查看msg参数以便进行准确的诊断和解决。
5、在进行图片操作时，系统会按顺序执行以下检查步骤，以确保文件可以被操作。首先，通过parse_url函数解析当前请求的URL路径，从中提取出文件名和域名等参数信息。如果请求的域名属于宫论域名，则获取对应的本地路径；否则，系统会立即返回，提示文件不支持操作。接着，系统使用file_exists函数检测文件是否存在，如果文件不存在，则返回相应的错误信息。随后，系统通过$manager->make方法尝试读取本地文件，如果在读取过程中出现异常，则返回相应的错误提示。最后，如果文件读取成功，系统会解析文件的MIME类型，以确保其为支持的类型；如果MIME类型不被支持，系统会返回错误信息。
6、宫论内置图片处理SDK现已扩展功能，不仅支持本地服务器图片的处理，还能处理外部图片。由于外部图片涉及下载操作，因此需要特别谨慎对待。具体流程如下：系统首先使用parse_url函数解析图片路径。如果图片来自本地服务器或是宫论域名指向的链接，则按照预设的参数进行处理。如果路径指向外部域名且包含scheme，则视为外部图片，此时系统会使用file_get_contents函数进行读取，读取操作设置了5秒的超时时间，以防止阻塞进程。若读取成功，图片将被暂时存储在临时文件中，随后按照标准流程进行
7、在使用 file_get_contents 发起远程图片下载请求时，为了确保安全性，将采取以下步骤进行处理。首先，会检查下载图片的文件名，确认其格式是否为支持的图片类型，如 jpg、jpeg、png、webp 等。如果文件格式不在支持列表中，将直接跳过此文件，避免下载非图片文件。接着，发起请求时会使用 @ 符号来抑制可能出现的警告，并通过 error_get_last 捕获潜在的错误信息。如果在下载过程中发生任何错误，将立即返回错误信息并中断操作。最后，还会检查图片是否成功保存，因为保存失败可能是由于权限等问题引起的。如果保存不成功，将返回相应的错误提示，以便进行进一步的排查和处理。
8、在使用 xc_imageManage_sdk 进行图片操作时，一旦成功读取图片对象，系统会立即调用并加载 SDK，同时创建一个 ImageManager 实例。接着，选择适合的图像处理库（如 gd）来进行处理，并将结果保存到【manager】中。此后，所有的图片操作都将通过这个对象进行管理。如果 SDK 初始化失败，或在 $manager->make 加载图片信息时遇到问题，系统将返回相应的错误信息，并中断当前任务的执行流程。
9、在使用ImageManager对图片对象进行操作和处理（如扩展、调整、压缩、转换）时，系统会采用try-catch机制来捕获异常。这些异常是在内部SDK进行对象操作时可能出现的。任何错误都会导致执行立即中断，系统将返回code=1，并附带具体的错误信息。与此同时，系统会将错误详细信息写入日志中。日志内容包括【处理时间：Y-m-d H:i:s，处理文件：由传入参数指定的image，处理请求：需要进行JSON转换的option参数，以及通过try-catch捕获的错误原因】。这些信息会被记录在【imageManage_sdk】日志中。需要注意的是，这类错误不会触发报警系统，仅负责错误信息的记录和存档，以便后续分析和改进。
10、在通过xc_imageManage_sdk发起图片处理请求并成功处理后，系统会将处理成功的图片直接保存到【$_SERVER['DOCUMENT_ROOT'] . '/cache/image/temporary'】目录中。如果在保存过程中出现失败，将会触发错误并终止脚本的执行。然而，一旦保存成功，系统将返回一个code=0的响应，同时附带一个额外的字段：link。这个link字段包含了指向已保存文件的路径。需要注意的是，为了防止文件名重复，文件命名采用了时间戳加随机数的方式进行生成，确保每个文件名的唯一性。
11、宫论通用图片处理SDK已完成封装处理，整个执行流程如下：1/输入参数：接受两个参数，image（图片地址）和 option（操作配置）。只支持通过图片链接传递，不支持直接传递图片对象。2、当 image 参数为宫论域名时，通过内置方法转换为本地绝对路径，确保处理的是合法的本地资源。3、对本地图片，检查文件是否存在并验证其MIME类型。4、对外部图片，下载并保存至临时文件夹，设置5秒超时以防止阻塞。5、使用 ImageManager 实例化处理引擎，默认使用 gd 库。如遇初始化或加载错误，立即返回错误信息。6、执行图片操作：根据 option 参数执行图像尺寸调整、压缩、格式转换及旋转等操作。过程中使用 try-catch 捕获异常，确保稳定性。7、处理成功后，图片保存在 /cache/image/temporary 目录中，采用时间戳和随机数生成唯一文件名。返回成功响应 code=0 及图片访问链接。8、任何操作错误均返回 code=1 并记录详细错误日志，包括处理时间、文件、请求参数及错误原因，便于后续分析。