# django52-v1
**Repository Path**: scboy/django52-v1
## Basic Information
- **Project Name**: django52-v1
- **Description**: 本应用为一个简单的通讯录系统，实现先后端分离，后端采用 Docker + Django5.2 + uWSGI + Nginx1.28 + Swagger + JWT + PostgreeSQL 16 , 踩了很多坑，不过搞定后很有成就感！欢迎交流学习。微信号：dwl5240
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 2
- **Forks**: 0
- **Created**: 2025-06-27
- **Last Updated**: 2025-08-15
## Categories & Tags
**Categories**: Uncategorized
**Tags**: Django, Docker, uWSGI, Swagger, PostgreeSQL
## README
# 开源通讯录系统 - 技术架构详解
基于Django + uniapp前后端分离架构的企业级通讯录管理系统，采用现代化技术栈实现高效部署与开发体验。
## 技术亮点
后端架构：Django 5.2 + uWSGI + Nginx 1.28 高性能组合
容器化部署：docker compose up -d (一键部署方案)
前端生态：Vue3 + ElementPlus 构建响应式管理界面
数据存储：PostgreSQL 16 提供可靠数据持久化
认证体系：JWT + Cookie 双认证机制保障系统安全
API 管理：Swagger 自动生成接口文档，提升开发效率
## 核心功能
支持 Excel、html、json、CSV等格式批量导入导出
基于django角色的权限管理系统
完善的用户认证与授权机制
响应式界面适配多终端设备
容器化部署简化运维流程，更注重系统的高可用性和安全性。
## 部署环境
操作系统：Ubuntu 24.04 LTS
容器化：docker-compose.yml + Dockerfile
Web 服务器：Nginx 1.28
应用服务器：uWSGI
数据库：PostgreSQL 16
欢迎技术爱好者参与交流，共同完善项目！
# 开发环境（部署到window11）
最好记住各环境配置的版本：避免冲突或者失效。
安装Python3.13.3
python --version #查看Python版本：3.13.3
pip --version # 查看pip版本25.1.1
1. 合适位置建立django项目目录（以E:\Python\django52-v1\目录为例）
在cmd下输入cd /D E:\Python\
mkdir django52-v1
2. 创建虚拟环境
cd django52-v1
python -m venv venv #新建虚拟环境。
venv\Scripts\activate #激活虚拟环境。 退出虚拟环境命令是： deactivate。
pip install django # 在激活的虚拟环境里，安装Django。用django-admin --version
或者 python -c "import django; print(django.get_version())" 查看Django版本：5.2。
2. 创建Django项目
django-admin startproject django_txl .
3. 创建django应用为：
python manage.py startapp django_txlapp # 不要用txlapp ，因为txlapp 是我之前的应用名，现在已经被占用了。
python manage.py startapp django_article_app # 文章应用
4. 创建数据库模型：
在django_txlapp与django_article_app应用中分别创建models.py文件，定义数据库模型。
创建模型.....
5. 创建完模型后，在settings.py里配置本地测试数据库.sqllite数据库，再执行以下步骤：
python manage.py makemigrations #生成迁移文件（每次修改模型后需要生成迁移文件并迁移数据库）
python manage.py migrate # 迁移数据库
python manage.py createsuperuser --username admin --email admin@123.com # 创建超级用户。Den*@*20
python manage.py runserver 0.0.0.0:8000 # 启动Django开发服务器。
## 登录后台，验证功能
浏览器打开：http://127.0.0.1:8000/admin/ 输入用户名和密码就能登录后台。
6. （可选）python manage.py check --deploy #检查部署。
7. 安装Swagger
8. 安装JWT
9. 安装pillow库
10. 安装djangorestframework-simplejwt 认证方式JWT认证需要安装包
11. 安装其他依赖库
## 验证API接口
两个应用的API将通过不同的前缀访问：
- 通讯录应用API: http://127.0.0.1:8000/api/txl/
- 部门列表: http://127.0.0.1:8000/api/txl/departments/
- 联系人列表: http://127.0.0.1:8000/api/txl/contacts/
- 文章应用API: http://127.0.0.1:8000/api/article/
- 文章列表: http://127.0.0.1:8000/api/article/articles/
- 栏目列表: http://127.0.0.1:8000/api/article/columns/
另外，你仍然可以通过 http://127.0.0.1:8000/api/docs/ 访问API文档，查看所有可用的API端点。
这种方式既保持了API的集中管理，又避免了路由冲突，使两个应用的API可以和谐共存。
在登陆状态下可以直接获取到数据，不登录状态下需要输入token才能获取到数据,获取token的方法有两种：
1. 访问 http://localhost:8000/api/token/ 输入用户和密码就能获取 token
2. 访问 http://localhost:8000/api/token/refresh/ 输入用户和密码就能获取 刷新token
2. 也可以
• 访问 http://localhost:8000/api/docs/
• 在页面最下面有 POST /api/token/列，输入用户名和密码，获取到JWT的token；复制。
• 点击右上角的"Authorize"按钮 • 输入获取的Token（格式：Bearer your_token_here）
• 点击"Try it out"按钮发送请求。
# 生产环境（部署到Ubantu24.04）
将windows系统里的项目文件传到ubantu系统去，建议使用 Git clong 仓库（高手推荐）
恢复前一定要导出依赖库：
pip freeze > requirements.txt # 导出依赖库。为以后恢复依赖备份，部署到生产环境也需要集成到Dockerfile文件。
## 环境准备
安装docker、docker compose，
准备环境
1. 如果是从新构建同名项目，推荐用portainer管理 (http://192.168.64.166:9000/ 登录 admin @Den*.12**5) 删除原来的django52-v1堆栈下容器，并删除镜像，网络，存储卷。
2. SSH登录到Ubuntu24.04服务器，默认在/home/deng/用户目录下，删除django52-v1目录及子文件。
'''
sodu rm -rf django52-v1/
'''
## 仓库克隆
3. 从远程仓库克隆下载新的项目文件（推荐，git仓库是经过.gitignore筛选后的最小内容，也更安全，配了 Python & Django 通用忽略 ）
'''
git clone https://gitee.com/scboy/django52-v1.git
'''
或者：通过winSCP上传项目文件到Ubuntu24.04服务器的新建django52-v1目录下。（不推荐）
## 构建镜像
4. cd django52-v1 #进入django52-v1目录。注意检查下 DEBUG = False # 生产环境必须设为False
5. docker compose up -d #首次启动会自动下载镜像并初始化数据库
根据提示：上传.env环境变量文件到django52-v1目录下（建议winSCP）。也可选择最简单的文件上传方案，使用Windows内置的scp命令，无需额外安装任何软件。 scp -P 2222 .env root@192.168.64.166:/home/deng/django52-v1/
## 创建超级用户：
6. 创建一个超级管理员admin，登录 Django 后台进行管理。（手动输入密码并确认）：
docker exec -it django52-v1-web-1 python manage.py createsuperuser --username admin --email admin@123.com #默认密码是Den*@*20。
6.1 恢复数据库
7. 访问项目前端、后台
纯IP访问。主机名不能访问！！！（待测试）
http://192.168.64.166/
http://192.168.64.166/admin #访问网站后台
http://192.168.64.166/api
http://192.168.64.166/api/docs #访问swagger。启用JWT和cooking双认证。
http://192.168.64.166/api/contacts/?format=json #json代码
8. 查看容器日志：
docker compose logs web
# 数据备份、恢复 （数据库用户密码看.env文件）
## 数据备份（包括用户系统）
最佳实践：用DBeaver软件备份。导出xlsx文件不推荐，性别恢复不了。
连接数据库登录后，在数据库栏目下的txldb上右键，选择”工具“-”备份“--选择备份文件”public"下一步--选择备份路径（如E:\Python\django_site\txlapp\sql_backups）----”开始“--完成。
## 数据恢复：
用DBeaver软件恢复数据库。
连接数据库登录后，在txldb--数据库栏目下的txldb上右键，选择”工具“-”恢复“--【切记】选择“在重建他们之前清理(删除)数据库对象”，选择备份文件E:\Python\django52-v1\sql_backups（如果为空选择文件名后面的下拉选择.sql文件）--”开始“--完成。
# 美化后台（自定义后台）
推荐：
https://mp.weixin.qq.com/s?__biz=MjM5OTMyODA4Nw%3D%3D&chksm=a73c69f8904be0eec3db8b8e2139a7c4c7ee851b04f0f8f1e0c8fa04f144249859df129abe60&idx=1&mid=2247485888&scene=21&sn=198a37f4a949685b9fb795ac5fa0c88b#wechat_redirect
https://blog.csdn.net/weixin_45776191/article/details/119112268
https://mp.weixin.qq.com/s/4bOwHCub-nbj4GjS-QuXRQ
pip install django-simpleui -i https://pypi.tuna.tsinghua.edu.cn/simple
配置settings.py
INSTALLED_APPS = [
'simpleui', #后台美化，在django.contrib.admin之前添加。
'django.contrib.admin',
。。。。
## 更改默认语言为中文
LANGUAGE_CODE = 'zh-hans'
注意：如果你在生成环境中使用SimpleUI，还需要使用python manage.py collectstatic命令收集静态文件，否则样式无法正常显示。
## 去掉默认Logo或换成自己Logo链接
SIMPLEUI_LOGO = 'https://th.bing.com/th/id/R2411a2b340731d67dfa0d84503e915e3?rik=zmYce%2fLys72JVQ&pid=ImgRaw'
## 设置simpleui 后台右上角，点击首页图标跳转的地址
SIMPLEUI_INDEX = 'http://www.dycmw.cn'
## 关闭右侧广告链接和使用分析
修改settings.py, 添加如下两行代码：
隐藏右侧SimpleUI广告链接和使用分析
SIMPLEUI_HOME_INFO = False
SIMPLEUI_ANALYSIS = False
现在查看效果，是不是清爽多了?
1. Django默认的admin模板都可以被重写。 在manage.py文件同级下创建模板文件 templates/admin/base_site.html。然后，打开设置文件mysite/settings.py，在TEMPLATES条目中添加一个DIRS选项：
```
'DIRS': [BASE_DIR / 'templates'], # 添加这一行
模板base_site.html 内容如下：
{% extends "admin/base.html" %}
{% block title %}{{ title }} | {{ site_title|default:_('Django site admin') }}{% endblock %}
{% block branding %}
{% endblock %}
{% block nav-global %}{% endblock %}
```
2. 修改管理后台的名称和标题要稍微复杂些，因为你不能直接在settings.py里进行配置。在任何一个app的目录下新建一个admin.py, 添加如下代码即可修改(本例app名为tasks)。这个设置属于Django的设置
```
# django_txlapp/admin.py
admin.site.site_header = '通讯录管理后台' # 设置header
admin.site.site_title = '通讯录管理信息系统' # 设置title
admin.site.index_title = '通讯录管理后台' #页面标题+后台右上角第二标题
```
3. 修改django_txlapp/apps.py, 通过verbose_name可以将app名改为中文.
```
from django.apps import AppConfig
from tabnanny import verbose
class TxlappConfig(AppConfig):
default_auto_field = 'django.db.models.BigAutoField'
name = 'django_txlapp'
verbose_name = '通讯录'
verbose_name_plural = '通讯录APP'
```
# 其它参考说明
## 创建目录
去Ubantu创建目标目录：如`~/python-projects/` ：
mkdir ~/python-projects/ #本用户名目录下创建文件夹，实际路径是/home/deng/python-projects
## Git说明
建议用Git克隆项目，推送main 分支代码到Gitee，然后在Gitee上创建一个新的仓库，将代码推送到新的仓库。
构建镜像前注意事项：1. 在settings.py里配置生产环境数据库链接信息，2. 确保requirements.txt文件里的依赖库已准备就绪。3. 确保.env文件里的环境变量已配置好。
包括：重启uWSGI服务、重启nginx服务、收集静态文件、迁移数据库、导入安装依赖库。
重启uWSGI服务：
docker exec -it django52-v1-web-1 uwsgi --reload /app/compose/uwsgi.ini
重启nginx服务：
docker exec -it django52-v1-nginx-1 nginx -s reload
收集静态文件：（省略，已集成到dockerfile里）
docker exec -it django52-v1-web-1 python manage.py collectstatic --noinput
迁移数据库：（省略，已集成到dockerfile里）
docker exec -it django52-v1-web-1 python manage.py migrate
导入安装依赖库 pip install -r requirements.txt #已经在Dockerfile 中配置了，这里不需要再执行。
requirements.txt文件里的依赖库在windowS系统中不需要安装 uWSGI==2.0.29.在ubantu环境用docker部署就需要，所以在Dockerfile文件里配置安装。
python manage.py collectstatic --noinput #已经在Dockerfile 中配置了，这里不需要再执行。
## 默认情况下，scp命令在上传文件时，如果目标位置已经存在同名文件，那么它会覆盖这个文件。
scp -P 2222 .env root@192.168.64.166:/home/deng/django52-v1/ #上传.env文件到django52-v1目录下。
## 将宿主机的文件复制到指定容器的指定目录
docker cp /usr/share/fonts/fontfile.ttf :/usr/share/fonts/
docker exec -it django52-v1-web-1 python manage.py makemigrations # 生成迁移文件。
docker exec -it django52-v1-web-1 python manage.py migrate # 迁移数据库。
docker exec -it django52-v1-web-1 python manage.py createsuperuser --username admin --email admin@123.com # 创建超级用户。
docker exec -it django52-v1-web-1 python manage.py check --deploy # 检查部署。
docker exec -it django52-v1-web-1 python manage.py check --database # 检查数据库。
docker exec -it django52-v1-web-1 python manage.py check --settings # 检查配置。
docker exec -it django52-v1-web-1 python manage.py check --installed-apps # 检查已安装应用。
docker exec -it django52-v1-web-1 python manage.py check --migrations # 检查迁移。
docker exec -it django52-v1-web-1 python manage.py check --urls # 检查URL配置。
docker exec -it django52-v1-web-1 python manage.py check --static-files # 检查静态文件。
docker exec -it django52-v1-web-1 python manage.py check --templates # 检查模板。
docker exec -it django52-v1-web-1 python manage.py check --cache # 检查缓存。
docker exec -it django52-v1-web-1 python manage.py check --sessions # 检查会话。
docker exec -it django52-v1-web-1 python manage.py check --security # 检查安全。
docker run -p 8000:8000 django51-txl #临时启动，日志都显示在当前终端。
Trae终端运行虚拟主机命令是：
trae up -d # 启动虚拟主机。
trae down -d # 停止虚拟主机。
powershell.exe -Command Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process -Force; venv\Scripts\Activate.ps1; python manage.py showmigrations
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple django-ckeditor-5
pip show django-ckeditor-5 # 查看安装信息