跳转至

作业

作业在QField云端对QGIS中的工程文件和图层执行大量的运算。作业是响应某些用户动作而创建的。

一旦创建了作业，就会被添加到工程的作业队列中，并等待可用的QField云资源去运行。在任何指定时刻，每个工程只能运行一个作业。其余排队作业的执行顺序与它们进入队列的顺序相同。

每项作业由一步或多步构成，每步负责工程中的一个独立任务。QField云支持三个预定义的作业工作流: process_projectfile 、 package 和 delta_apply 。

运行时，作业写入日志消息，这些消息可在工程的作业页面上找到，用于已达到最终状态 FINISHED 或 FAILED 的作业。

作业可以访问 工程机密消息 。

笔记

可以使用QField云API触发所有作业。

警告

  • 本页中描述的任何触发条件可能会更改，恕不另行通知。
  • 所有作业必须在10分钟内完成，否则将导致超时错误并终止。

Info

If you are looking for technical details how Jobs work, check the Job Queue documentation.

作业类型

处理工程文件 (process_projectfile) 作业

处理工程文件作业用于提取工程配置和工程图层的详细信息，例如工程CRS、图层CRS、图层名称、图层有效性等。QField云验证上传的QGIS工程文件 (.qgs/.qgz)以及支持的地理包、TIFF和其他数据源文件，还验证与PostGIS、WFS、WMS和其他在线数据源的远程连接。QField云将在服务器的QGIS实例中打开工程文件，用于提取所有必要的信息。

触发器

每次将文件上传到QField云时都会触发此作业，除非以下条件中至少有一项有效：

  • 尚未上传任何QGIS工程文件 (.qgs/.qgz) 。
  • 上传的文件位于 DCIM 目录。假定这些文件与工程有效性无关。
  • 已存在处于 PENDING 状态的 process_projectfile 作业。

解决问题

process_projectfile 作业可能会导致出现 FAILED 状态。请检查以下非详尽的原因列表：

  • 上传的QGIS工程文件 (.qgs/.qgz) 是不可读、不完整、损坏或错误等，请尝试重新上传QGIS工程文件。
  • QGIS打开工程文件后崩溃。尝试通过从工程中一次移除一个图层并重新上传QGIS工程文件来识别导致崩溃的图层。

笔记

即使 process_projectfile 作业导致 SUCCESS 状态，也不意味着工程配置正确。 SUCCESS 状态仅表示工程已成功打开，并且已提取所有所需信息。

打包 (package) 作业

package 作业将QGIS工程转换为QField工程，与在QGIS通过QFieldSync完成的方式相同。 package 作业将标记为 "离线编辑" 的所有图层配制到单地理包中。

触发器

每当按下QField中的 下载 或 同步 按钮时，将触发此作业。除非以下条件中至少一项有效：

  • 该工程从未运行过导致 SUCCESS 状态的 process_projectfile 作业。
  • 已存在处于 PENDING 状态的 package 作业。
  • 该工程不包含在线矢量图层 (PostGIS、WFS等)，最新的 package 作业结果是 SUCCESS ，没有文件上传，也没有更改上传。

解决问题

package作业可能会导致 FAILED 状态。请检查以下非详尽的原因列表：

  • 该工程从未运行过导致 SUCCESS 状态的 process_projectfile 作业。
  • 某些工程图层从QField云无法访问。请确保所有文件都已上传，所有在线图层 (PostGIS、WFS等) 的网络凭证都存储在QGIS工程文件中。

Delta 应用 (delta_apply) 作业

Delta应用作业负责将所有推送QField的更改永久化。

触发器

每次在QField按下 同步 或 推送更改 按钮，或在 更改 工程页面按下 应用挂起的更改 按钮时，将会触发此作业。如果以下任一条件有效：

  • 该工程从未运行导致 SUCCESS 状态的 process_projectfile 作业。
  • 已存在处于 PENDING 状态的 delta_apply 作业。

解决问题

delta_apply 作业可能会导致 失败 状态，请检查以下非详尽的原因列表：

  • QGIS工程中使用的至少一个在线数据库 (PostGIS/WFS) 重置了连接。
  • 工程太大，作业无法运行。
  • 工程中存在隐藏的文件和目录，这些文件和目录妨碍了QField云的正常工作。隐藏文件和目录是以前导点 (.) 开头的。
Understanding conflicts delta_apply jobs

Conflicts can occur under the following conditions:

  1. Two or more users modify the geometry or a specific attribute of the same feature, starting from the same initial value but saving different values.
  2. A primary key is used more than once.

To minimize the risk of conflicts, follow these best practices:

  • Plan updates collaboratively - When updating features based on specific field conditions, assign each user a distinct set of features to edit. Clear planning reduces overlap and potential conflicts.
  • Avoid modifying primary keys - Primary keys should be treated as immutable and configured to be read-only. This ensures consistent identification of features and prevents accidental modifications.
  • Ensure unique primary keys - Use a truly unique primary key, such as a UUID (uuid()), to prevent conflicts and ensure data integrity.

By implementing these practices, you can significantly reduce the likelihood of conflicts and maintain consistent data.

How to resolve conflicts?

By default, QFieldCloud overwrites conflicts using a last wins policy (the latest patch of changes to the attribute(s) involved in the conflict replaces all earlier patches of changes to these attributes). Alternatively, admins can set a project's conflict resolution policy to manual. Doing so will require the project manager to manually resolve conflicts, picking those to be applied to the project.

  1. Navigate to the "Changes" section.
  2. Filter the changes with the "CONFLICT" status.
  3. For each conflicted change, select it and set the status to "Re-apply" from the "Action" dropdown menu, alternatively if all the new changes are in conflict you can choose in the last conflicted change and select "Re-apply this and newer changes".
  4. Check the details of changes in the conflict and click "Save All" at the end of the page.

在QFieldCloud中重新应用更改
  1. 单击 我的工程 中的工程名称。
  2. 转到 更改 部分 (更改按从最新到最旧排序)。
  3. 查找要重新应用的特定更改。
  4. 在右侧的 动作 列中，单击下拉列表。

  5. 选择所需的动作以重新应用更改。

    • 重新应用特定更改：如果需要重新应用特定的更改，请选择要重新应用的每个更改，然后单击 重新应用 。
    • 重新应用最近的更改：如果希望重新应用对工程所做的最新修改，请确定要恢复的初始更改，然后选择 重新应用此更改和更新的更改 。

最后，单击 全部保存 按钮。

重新应用更改
重新应用更改

作业日志疑难解答

运行作业时，通常可以在日志中找到一个名为 "检查工程图层" 的步骤，该步骤将输出一个表，其中包含所有工程图层及其所处的状态。

可能的状态为：

  • ok - 该图层在QField云正确加载。
  • invalid_dataprovider - 图层的数据提供程序无效。通常，附加信息显示在 "提供程序摘要" 中。
  • invalid_layer - 这种错误应该很少发生。数据加载正确，但由于某些原因，QGIS报告该图层无效。

无法连接到服务 "{SERVICE}" 。

QFieldCloud尝试连接到不可用的PostgreSQL服务。您应该需要创建一个新的 pgservice 机密 ，便于QFieldCloud可以连接到PostGIS服务。

无法连接到主机 "{HOST}" 。

QFieldCloud无法建立给定 {HOST} 的连接。无法从QFieldCloud服务器访问您的服务。您可能会要求 IT 部门将 QFieldCloud IP 列入白名单 。

无法连接到主机 "localhost" 。

您已上传一个连接到本地计算机的数据库/服务的图层。移除该图层或用QFieldCloud可访问的图层源进行替换。

文件 "{FILENAME}" 丢失。

在QFieldCloud服务器找不到文件 {FILENAME} (例如 /tmp/rndstr/files/data.gpkg) ，因此无法打开。有两种情况需要检查：

  • 文件是否已上传到云端。您可以在QFieldCloud或QFieldSync的 工程设置 -> 文件 页面中检查此项。
  • 确保文件以与PC上相同的相对路径上传。请注意， 所有 工程文件都应位于与 .qgs/.qgz QGIS工程文件相同的工程目录或子目录中。还请注意，目录名也应保留，例如，如果文件存储在 data/data.gpkg ，请确保QFieldCloud端也存在此 data 目录。