freezingsaddles/freezing-web

Freezing Saddles Web

镜像概述和主要用途

Freezing Saddles Web是Freezing Saddles（又名BikeArlington Freezing Saddles，"BAFS"）基于Strava的冬季骑行竞赛软件的Web组件。该应用由多个协同工作的组件构成（设计为Docker容器运行），Web组件主要负责提供排行榜查看功能。

注：完整系统包含以下组件：

1. https://github.com/freezingsaddles/freezing-web - 用于查看排行榜的网站
2. https://github.com/freezingsaddles/freezing-model - 包含共享数据库和消息类的库
3. https://github.com/freezingsaddles/freezing-sync - 从Strava同步骑行数据的组件
4. https://github.com/freezingsaddles/freezing-nq - 接收Webhook并将其排队等待同步的组件

核心功能和特性

• 提供直观的排行榜展示界面，显示冬季骑行竞赛的参与者和团队排名
• 支持Strava用户认证与授权，实现用户登录和数据访问
• 展示运动员骑行数据、团队统计信息及竞赛进度
• 基于SQLAlchemy的数据库交互，支持数据持久化和查询
• 可通过环境变量灵活配置，适应不同部署环境需求

使用场景和适用范围

• 冬季骑行竞赛活动的官方网站，供参与者查看实时排名
• 竞赛组织者管理和展示竞赛数据的平台
• 骑行爱好者跟踪个人和团队在冬季竞赛中的表现

详细使用方法和配置说明

开发环境设置

依赖项

• Python 3.6+（不支持Python 2.x）
• Pip
• Virtualenv (venv)
• MySQL 5.6+

建议直接在工作站上安装Python 3.6和pip以方便开发调试，已在macOS 13.x（High Sierra）、多种Linux发行版和Windows 10上测试通过。

安装步骤

bash
# 克隆仓库
shell$ mkdir freezingsaddles && cd freezingsaddles
shell$ for part in sync web compose nq model; do git clone https://github.com/freezingsaddles/freezing-$part.git; done

# 为freezing-web创建并激活虚拟环境
shell$ cd freezing-web
shell$ python3.6 -m venv env
# Windows系统使用: env/Scripts/activate
shell$ source env/bin/activate
(env) shell$ pip install -r requirements.txt
(env) shell$ python setup.py develop

后续命令均假设在激活的freezing-web虚拟环境中运行（命令前缀为"(env) shell$"）。

数据库设置

使用Docker设置数据库

可使用开发支持的Docker Compose文件简化数据库设置，详见https://github.com/freezingsaddles/freezing-compose%E4%BB%93%E5%BA%93%E8%AF%B4%E6%98%8E%E3%80%82

手动设置数据库

安装MySQL 5.6或更高版本（生产服务器使用MySQL 5.6）。创建数据库和用户：

bash
shell$ mysql -uroot
mysql> create database freezing;
mysql> grant all on freezing.* to freezing@localhost;

配置和运行服务器

配置文件为shell环境文件（也可直接使用环境变量）。可参考示例文件example.cfg，需设置环境变量APP_SETTINGS指向配置文件路径。

使用新的development.cfg配置文件启动Web服务器示例：

bash
(env) shell$ cp example.cfg development.cfg
# 编辑配置文件
(env) shell$ APP_SETTINGS=development.cfg freezing-server

关键配置项：

• 数据库URI
• Strava客户端信息（ID和密钥，用于测试注册/授权/登录）

配置文件示例：

bash
# MySQL数据库的SQLAlchemy连接URL（注意字符集）
# 注意：如果使用Docker，主机使用127.0.0.1而非localhost
SQLALCHEMY_URL=mysql+pymysql://freezing@localhost/freezing?charset=utf8mb4&binary_prefix=true

# 创建Strava应用时获取的客户端信息
# 仅在测试应用授权或登录功能时需要
STRAVA_CLIENT_ID=xxxx1234
STRAVA_CLIENT_SECRET=5678zzzz

与freezing-model协同开发

由于多个项目依赖freezing-model，开发时可能需要修改该库。按以下步骤可在本地开发环境中链接freezing-model：

1. cd ~/workspace/freezing-web
2. python3 -m venv env
3. source env/bin/activate
4. cd ~/workspace/freezing-model
5. pip install -r requirements.txt && python setup.py develop
6. cd -
7. pip install -r requirements.txt && python setup.py develop

永久使用修改后的freezing-model需为其创建新版本标签并更新freezing-web/requirements.txt中的版本号。

编码标准

代码需符合https://www.python.org/dev/peps/pep-0008/%E8%A7%84%E8%8C%83%EF%BC%8C%E4%BD%BF%E7%94%A8https://black.readthedocs.io/en/stable/%E8%BF%9B%E8%A1%8C%E6%A0%BC%E5%BC%8F%E5%8C%96%EF%BC%8Cflake8%E8%BF%9B%E8%A1%8C%E4%BB%A3%E7%A0%81%E6%A3%80%E6%9F%A5%E3%80%82%E5%AE%89%E8%A3%85%E6%B5%8B%E8%AF%95%E4%BE%9D%E8%B5%96%E4%BB%A5%E8%8E%B7%E5%8F%96%E8%BF%99%E4%BA%9B%E5%B7%A5%E5%85%B7%EF%BC%9A%60pip install -r test-requirements.txt`。

Docker部署

完整部署指南见https://github.com/freezingsaddles/freezing-compose%E3%80%82%E8%AF%A5%E7%BB%84%E4%BB%B6%E8%AE%BE%E8%AE%A1%E4%B8%BA%E5%AE%B9%E5%99%A8%E8%BF%90%E8%A1%8C%EF%BC%8C%E9%9C%80%E9%85%8D%E7%BD%AE%E4%BB%A5%E4%B8%8B%E7%8E%AF%E5%A2%83%E5%8F%98%E9%87%8F%EF%BC%9A

• DEBUG: 是否显示异常堆栈跟踪等调试信息
• SECRET_KEY: 用于加密Flask会话cookie的密钥
• BEANSTALKD_HOST: beanstalkd服务器主机名（可能是容器链接）
• BEANSTALKD_PORT: beanstalkd服务器端口（默认***）
• SQLALCHEMY_URL: 数据库URL
• STRAVA_CLIENT_ID: Strava应用ID
• STRAVA_CLIENT_SECRET: Strava应用密钥（可从Strava应用设置页面获取）
• TEAMS: 竞赛团队（Strava俱乐部）ID的逗号分隔列表（格式：cast=list, subcast=int, default=[]）
• OBSERVER_TEAMS: 仅观察不参与竞赛的团队ID逗号分隔列表（可包含整体统计但不计入排行榜）
• START_DATE: 竞赛开始日期
• END_DATE: 竞赛结束日期

年初流程

1. 创建新的Strava主群组（通常由负责注册流程的人员创建）
2. 从Strava俱乐部"最近活动"页面URL获取数字俱乐部ID
3. 通过SSH访问生产服务器
4. 确保可访问生产数据库（通过SSH端口转发、Docker内MySQL客户端等方式）
5. 备份数据库：

   bash
   mysqldump > "freezing-$(date +'%Y-%m-%d').sql"
   

6. 备份/opt/compose/.env文件：

   bash
   cp /opt/compose/.env "/opt/compose/.env-$(date +'%Y-%m-%d')"
   

7. 编辑生产服务器的.env文件（路径/opt/compose/.env）：
   • 更新开始和结束日期
   • 更新主Strava团队ID MAIN_TEAM
   • 清除TEAMS和OBSERVER_TEAMS中的所有团队
   • 更新竞赛标题COMPETITION_TITLE以反映新年份
   • 修改注释以反映新年份
8. 删除以下MySQL表中的所有数据（详见https://github.com/freezingsaddles/freezing-web/blob/master/freezing/sql/year-start.sql%EF%BC%89%EF%BC%9A
   • teams
   • athletes
   • rides
   • ride_geo
   • ride_weather
9. 向teams表插入与MAIN_TEAM ID匹配的新记录：

   sql
   insert into teams values (567288, 'Freezing Saddles 2020', 1);
   

10. 重启服务：

    bash
    cd /opt/compose && docker-compose up -d
    

11. 团队公布后（通常在1月初的欢乐时光活动）：
    • 在生产.env文件中添加竞赛团队和观察团队ID
    • 重启服务：

      bash
      cd /opt/compose && docker-compose up -d
      

运动员加入指定竞赛团队后将自动分配到正确团队。

***信息

本软件是社区驱动的成果，贡献归各贡献者所有：

Copyright 2015 Ian Will
Copyright 2019 Hans Lillelid
Copyright 2020 Jon Renaut
Copyright 2020 Merlin Hughes
Copyright 2020 Richard Bullington-McGuire
Copyright 2020 Adrian Porter
Copyright 2020 Joe Tatsuko

本软件根据Apache 2.0许可证授权，部分标记内容采用兼容许可证（如[MIT许可的test/wget-spider.sh]）。