MacPorts Web应用Docker镜像文档

镜像概述

应用目标

该Web应用主要实现以下功能：

1. 显示所有端口的一般信息
2. 获取并显示端口的构建历史
3. 收集并显示安装统计数据（系统配置和已安装端口），数据来自选择安装mpstats端口的用户

应用旨在为用户提供一站式端口查找平台，同时帮助维护者监控其端口并了解用户群体。生产环境实例运行于ports.macports.org。

更多信息参见docs/1-INFORMATION.md

架构说明

Web应用基于Django框架开发，使用PostgreSQL数据库。
应用推荐部署在Docker容器中，通过nginx和uWSGI提供服务。

该应用是在Google Summer of Code 2019期间由MacPorts组织指导开发：
学生：Arjun Salyan
导师：Mojca Miklavec、Umesh Singla

核心功能与特性

• 端口信息展示：提供端口的基本信息查询
• 构建历史追踪：获取并展示端口的构建历史记录
• 安装统计收集：收集选择安装mpstats端口的用户的系统配置和安装端口数据
• 自动化更新：通过定时任务自动更新端口索引和构建历史
• 容器化部署：支持Docker容器化部署，包含预配置的迁移和静态文件收集

使用场景

• 用户：查找端口信息、了解端口构建历史
• 维护者：监控端口使用情况、分析用户群体、跟踪构建状态
• 开发环境：快速部署应用进行功能测试和开发

使用方法与配置说明

1. Docker容器内运行（推荐方式）

Docker镜像已预配置自动运行migrations和collectstatic命令，需手动执行初始数据填充和定时任务启动。

1.1 获取镜像

可直接拉取镜像或本地构建：

# 拉取镜像
docker pull arjunsalyan/macports-webapp

# 或本地构建
docker build -t macports-webapp .

1.2 创建环境变量文件

在项目根目录创建env文件，配置以下环境变量（参考项目根目录的env.sample文件）：

DB_NAME=数据库名称
DB_USER=数据库用户名
DB_PASSWORD=数据库密码
DB_HOST=数据库主机地址（连接主机数据库时使用host.docker.internal代替localhost）
DB_PORT=数据库端口（默认：5432）
SECRET_KEY=Django应用密钥

1.3 启动容器

docker run -d -p 80:80 --env-file=env --name=macports-webapp macports-webapp

访问127.0.0.1:80验证启动状态（首次加载可能需10-15秒，后台执行迁移和静态文件收集）。

1.4 填充初始数据

仅在空数据库上执行，从rsync服务器获取最新PortIndex.json并填充数据库：

docker exec macports-webapp python3 /code/app/manage.py autoload-initial-data

注：该过程耗时较长（通常30分钟内，取决于数据库与应用的连接速度）。

1.5 启动定时任务

数据填充完成后启动定时任务：

docker exec macports-webapp supervisorctl start cron

启动后将自动执行以下任务：

• 每小时执行一次构建历史获取：python3 manage.py fetch-build-history
• 每三小时执行一次端口索引更新：python3 manage.py update-portinfo

1.6 执行其他命令

应用支持的其他命令通过以下方式执行：

docker exec macports-webapp [命令]

2. 非Docker环境运行

/app目录为独立Django应用，可按标准Django应用方式运行。

2.1 数据库配置

推荐通过环境变量配置数据库连接（避免直接修改配置文件），需设置以下环境变量：

DB_NAME=数据库名称
DB_USER=数据库用户名
DB_PASSWORD=数据库密码
DB_HOST=数据库主机地址
SECRET_KEY=Django应用密钥

不推荐方式：直接修改app/MacPorts/settings.py文件配置数据库凭据。

2.2 数据库迁移

# 创建迁移文件
python3 manage.py makemigrations

# 执行迁移
python3 manage.py migrate

2.3 填充初始数据

1. 在项目根目录放置portindex.json文件（通过portindex2json.tcl生成）
2. 加载端口、分类和维护者数据：

   python3 manage.py load <文件名>  # 不指定文件名则使用默认portindex.json
   

3. 获取最近构建记录：

   python3 manage.py fetch-build-history
   

2.4 启动服务器

# 收集静态文件
python3 manage.py collectstatic

# 启动开发服务器
python3 manage.py runserver

2.5 更新数据库

将新的JSON文件放置在项目根目录，执行更新命令：

python3 manage.py update <文件名>  # 不指定文件名则使用默认portindex.json

支持基于提供的JSON文件特性进行差异更新或全量更新。