# xjobs

**Repository Path**: xueshanlinghu/xjobs

## Basic Information

- **Project Name**: xjobs
- **Description**: 一个基于 Python 3 开发的定时任务调度平台。

开发者：雪山凌狐

x取雪的第一个字母。

开发的初衷是给自己的云服务器整一个自己写的定时任务调度平台，用来完成一些需要定时调度的任务，比如python，bat，存储过程或者其他等等。

比较适合放到自己的服务器上使用。

因为我是在win平台开发和在win server平台使用的，目前仅保证win平台的正常运转，其他平台请自行尝试。
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: https://gitee.com/xueshanlinghu/xjobs/releases
- **GVP Project**: No

## Statistics

- **Stars**: 5
- **Forks**: 7
- **Created**: 2020-01-13
- **Last Updated**: 2025-08-18

## Categories & Tags

**Categories**: task-schedule

**Tags**: None

## README

# xjobs



#### 介绍
一个基于 Python 3 开发的定时任务调度平台。

**开发者：雪山凌狐**

x取雪的第一个字母。

开发的初衷是给自己的云服务器整一个自己写的定时任务调度平台，用来完成一些需要定时调度的任务，比如python，bat，存储过程或者其他等等。同时感谢我的领导对我的指导帮助。

比较适合放到自己的服务器上使用。

因为我是在win平台开发和在win server平台使用的，目前仅保证win平台的正常运转，其他平台请自行尝试。



如有其它学习需要，欢迎来我的博客找我：

[雪山凌狐教程http://www.xueshanlinghu.com](http://www.xueshanlinghu.com)



#### 必要环境安装

1. Python 3已安装到电脑上，为避免一些低版本python存在的报错问题，本程序维护支持的最低python版本为python3.6。程序已在最低3.6.6版本系统上测试成功。

2. python必备三方包安装：

   - Apscheduler：

     ```python
     pip install apscheduler
     ```



#### 使用方法

##### 首次使用：

1. 将最新的发行版 [https://gitee.com/xueshanlinghu/xjobs/releases](https://gitee.com/xueshanlinghu/xjobs/releases) download到本地并解压。

2. 首次使用，请打开cmd命令提示符，进入xjobs所在的文件夹，运行如下命令启动它测试有没有问题：

   ```python
   python xjobsConsole.py
   ```

   如果问题的提示，无法启动的，按照提示进行解决处理。

   常见的几个问题：

   - 提示导入apscheduler模块出错。解决办法：按照我们**必要环境安装**部分中所述，先进行该包的安装。

   - 提示xjobs所支持的最低python版本为3.6。解决办法：请保证你安装了至少python3.6以上的版本。或告知我给你打包一份exe版本的xjobs来使用（也可以自己修复问题代码后自己打包）。

   - 其他错误提示请根据你的实际情况进行解决。解决不了的，可以告知我或者提issue。

##### 后续使用：

1. 测试无问题后，后续使用及未来使用，可以通过双击“启动xjobs定时调度平台.bat”这个文件启动xjobs调度平台。（也可以将该bat文件放到某个地方的快捷方式，比如桌面）

   内含代码如下：

   ```bat
   python xjobsConsole.py
   ```

2. **如何添加定时任务配置呢？**

   安装DB Browser或者SQLite Studio等数据库软件，打开**xjobs.db**数据库文件进行编辑。

   **（我已配置了一个测试任务，如果你不配置你自己的也能测试使用。后续使用可以对自己的任务进行数据库配置）**

   程序暂未提供数据库可视化配置的功能，需要你自己写sql语句或者使用可视化数据库软件自行配置。（未来可能会考虑做成前台可视化配置）

   内含好几张预设表，他们的作用分别如下：

   - **sqlite_sequence：sqlite**表序列存储表，自动生成，自动填写，你无需理会。

   - **xjobs_dictionary：xjobs**数据字典表，对数据库的各个表和字段做了充分详尽的解释，你可以把它看做一个字典，可以不维护，也可以自行按照里面的规范进行维护。

   - **xjobs_task**：我们**最重要**的需要进行配置的表，里面包含许多的字段，某些字段是必填项，你可以根据字典里面的指引或者参考我给你的测试任务的填写范例进行填写。

     其中，**is_pause**字段控制该行的定时任务是否启用，为0则启用，为1则暂停，如果你不需要测试任务了，可以设置为1。

     **update_time**字段为更新时间，我设置了一个触发器，会自动进行时间的更新，你无须自行填写。

     **cron_exp**字段为配置时需要特别关注的点，它为cron定时表达式。它的填写指引如下：

     ```python
     '''
     顺序单位：   秒     分     时     日     月     周      年(年一般省略不写)
     
     【cron表达式介绍】
     *：触发所有值
     */a：a从最小值开始，触发每个值
     a-b：触发a-b范围内的任何值（必须小于b）
     a-b/c：触发在a-b之间的每个c值
     xth y：顺数第x个星期y触发，如2nd sun意思为第二个星期天触发【请务必理解后才使用】
     last x：在一个月的最后一个星期x触发，如last fri意思为最后一个星期五【请务必理解后才使用】
     last：在月末的最后一天触发
     x,y,z：触发任何匹配的表达式; 可以组合任意数量的任何上述表达式。
     
     注意：xth y,last x,last这3个是用在day（即日）参数中，其它所有参数都可以使用。
     【注意】如果使用了xth y,last x等这几个表示day，中间有空格的，请在表达式中，使用单引号或双引号引起来，否则不生效！！
     请勿在除了day以外的表达式部分中使用这几项，否则会出错！
         
     【补充很多网上没有的】：
     星期几有啥选项？
     WEEKDAYS = ['mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun']
     月份有啥选项？
     MONTHS = ['jan', 'feb', 'mar', 'apr', 'may', 'jun', 'jul', 'aug', 'sep', 'oct', 'nov', 'dec']
     排序，第几个有啥选项？
     options = ['1st', '2nd', '3rd', '4th', '5th', 'last']
     '''
     ```

   举例：

   ```python
   */10 * * * * *    #每10的整除秒数执行一次，比如10、20、30、40、50、60秒
   0 50 * * * *    #任意小时的50分0秒执行一次
   * 50 * * * *    #任意小时的50分的每一秒都触发执行一次，即该小时共会执行60次（务必区别于上面那种写法）
   0 0 6 * * *    #任意天的6点触发执行一次
   0 0 6 28 * *    #每月28日的6点执行一次
   0 0 6 'last fri' * *    #在每月最后一个星期五的6点触发执行一次（务必加上单引号或双引号引起来，day部分）
   56 30 8 '2nd sun' feb,apr *    #在二月、四月的第二个星期天的8点30分56秒执行一次（记得加引号哦）
   ```

   配置好数据库后，保存数据库。

3. **当定时任务运行异常有没有监控？**

   目前有自带邮件监控功能，默认为禁用状态False。启用后，当定时任务日常运行有错误时可以及时通过邮件发送给你。

   如果你需要使用，需要先到xueshan_utils文件夹下，找到“xs_sendmail_setting模板.py”这个文件进行配置的编辑：

   - sender，发件人

   - receiver，收件人，支持多个，使用英文逗号,分隔

   - username，登录邮箱的用户名

   - password，登录邮箱的密码

   程序采用的是基于QQ邮箱SMTP服务的发邮件程序，你需要先到你计划用来发邮件的QQ邮箱设置中，开启SMTP服务，同时获取到一串像token一样的密码。然后进行配置。如果这里你不清楚如何做，或者没用过QQ邮箱的SMTP服务，你可以尝试考虑其他邮箱的或者咨询我。实在不行，不要启用该功能就好了。

   编辑好之后，保存该文件，并务必将该文件的文件名中的“模板”两个字删除，才能生效。

   完成后，打开xjobsConsole.py主程序文件，找到如下代码：

   ```python
   USE_MAIL = False
   ```

   将其中的**False**修改为**True**即可启用。

   未来的版本可能还会添加短信提醒或微信提醒的功能，看情况吧，目前暂时不支持。

   

##### 祝您使用愉快！



#### 更新日志

V1.4 版本 20200511：

1. 更新初始数据库字典，bat改为正确的cmd。
2. 修复在执行cmd或者bat命令时报错的问题。



V 1.3 版本 20200210：

1. fix-issue 多次任务运行后后台存在多个python子进程的问题。



V 1.2 版本 20200130：

1. 修复上一版本当监听异常时，获取traceback信息代码执行报错的问题
2. 优化雪山共同类的cron表达式处理功能，使之能够正确处理cron表达式的day部分使用last x或xth y样式。
3. README文件增加大量cron表达式的填写范例和说明
4. 升级说明：基于上一版本，将旧版本的xjobs.db文件备份，下载新版本覆盖后，还原你的xjobs.db数据库即可。



V 1.1 版本 20200129：

1. 修复上一版本仅支持python3.7以上，但以下一些命令会报错的问题。并将程序版本支持最低定位到python3.6。
2. 优化了报错提示和版本检测，给初次使用者更好的交互体验。
3. 针对xjobs的使用方法方案进行大量的更新，更新内容均写在README文件中。
4. 新增邮箱监控使用的配置，默认设置为不启用邮件监控，避免一些同学还没设置好邮箱配置而报错无法开始使用的问题，降低初次使用门槛。



V 1.0 版本 20200128：

1. 完成xjobs定时任务调度框架的绝大部分功能和测试，达到上线水平，即将部署到生产环境。

   欢迎大家尝试使用，如有问题，可以向我反馈或发起Pull Requests。