# full-stack-fastapi-template_for_ai_web

**Repository Path**: xianyuone/full-stack-fastapi-template_for_ai_web

## Basic Information

- **Project Name**: full-stack-fastapi-template_for_ai_web
- **Description**: No description available
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2024-08-25
- **Last Updated**: 2024-11-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

## 项目目录结构与文件说明
## Project Directory Structure and File Description

你列出的文件和目录结构代表了一个典型的基于微服务架构的项目布局，其中包含了前端、后端、数据库和其他辅助服务的定义。下面是各个文件和目录的作用：

The file and directory structure you've listed represents a typical layout for a microservices-based project, including definitions for frontend, backend, database, and other auxiliary services. Here's the purpose of each file and directory:

- **.copier**, **.github**, **.vscode**
  - 分别是Copier模板配置、GitHub工作流和VSCode编辑器配置的目录。
  - These are directories for Copier template configuration, GitHub workflows, and VSCode editor configuration, respectively.

- **backend**, **frontend**
  - 分别是后端和前端服务的代码目录。
  - These are code directories for backend and frontend services, respectively.

- **hooks**, **img**, **scripts**
  - 可能包含项目构建、部署或自动化任务的脚本、图像资源和Git钩子。
  - May contain scripts for project building, deployment or automation tasks, image resources, and Git hooks.

- **.env**
  - 存储项目的环境变量，例如数据库连接字符串、API密钥等敏感信息。
  - Stores environment variables for the project, such as database connection strings, API keys, and other sensitive information.

- **.gitattributes**, **.gitignore**, **.pre-commit-config.yaml**
  - 分别是Git属性配置、Git忽略文件列表和预提交Hook配置。
  - These are Git attribute configuration, Git ignore file list, and pre-commit hook configuration, respectively.

- **copier.yml**
  - Copier是一个用于创建项目模板的工具，此文件定义了项目模板的结构和变量。
  - Copier is a tool for creating project templates, and this file defines the structure and variables of the project template.

- **deployment.md**, **development.md**, **release-notes.md**, **SECURITY.md**
  - 分别是部署指南、开发指南、发布说明和安全政策文档。
  - These are deployment guide, development guide, release notes, and security policy documents, respectively.

- **LICENSE**
  - 项目的许可协议。
  - The license agreement for the project.

- **README.md**
  - 项目的主要说明文档，通常包含项目介绍、安装和使用说明。
  - The main documentation for the project, typically containing project introduction, installation, and usage instructions.

- **docker-compose.yml**, **docker-compose.override.yml**, **docker-compose.traefik.yml**
  - 分别是Docker Compose的基本配置、覆盖配置和Traefik反向代理配置文件。
  - These are Docker Compose's basic configuration, override configuration, and Traefik reverse proxy configuration files, respectively.

### Docker Compose 配置示例中的服务
### Services in the Docker Compose Configuration Example

在你提供的`docker-compose.yml`配置示例中，定义了以下服务：

In the `docker-compose.yml` configuration example you provided, the following services are defined:

- **db**: PostgreSQL数据库服务。
- **db**: PostgreSQL database service.

- **adminer**: 数据库管理工具Adminer，用于图形化管理数据库。
- **adminer**: Adminer database management tool, used for graphical database management.

- **backend**: 后端服务，可能是一个API服务器。
- **backend**: Backend service, likely an API server.

- **frontend**: 前端服务，可能是一个Web应用程序。
- **frontend**: Frontend service, likely a web application.

这些服务通过网络和环境变量相互关联，例如后端服务依赖于数据库服务，并且可以通过`.env`文件中的环境变量进行配置。此外，Traefik被用作反向代理，用于处理HTTP和HTTPS请求，实现域名重定向和TLS加密。

These services are interconnected through networks and environment variables. For example, the backend service depends on the database service and can be configured using environment variables in the `.env` file. Additionally, Traefik is used as a reverse proxy to handle HTTP and HTTPS requests, implementing domain redirection and TLS encryption.

### 总体概述
### Overall Overview

总体而言，这些文件和目录构成了一个全面的项目框架，支持从开发到部署的整个流程。

Overall, these files and directories constitute a comprehensive project framework, supporting the entire process from development to deployment.

## 文件结构与功能概述
## File Structure and Functionality Overview

此项目是一个基于FastAPI后端和React前端的Web应用。以下是各部分的详细描述：

### 根目录 (D:.)
- **.copier**: 存储Copier模板配置，用于快速生成和管理项目文件。
- **.github**: 包含GitHub相关的元数据和工作流配置。
  - **DISCUSSION_TEMPLATE**: 讨论模板，用于指导用户如何发起讨论。
  - **ISSUE_TEMPLATE**: 问题模板，帮助用户提交高质量的问题报告。
  - **workflows**: GitHub Actions工作流定义，自动化构建、测试等任务。
- **.vscode**: Visual Studio Code编辑器的配置文件和扩展设置。
- **backend**: 后端服务源代码，使用FastAPI框架。
  - **app**: 主要的后端应用程序目录。
    - **alembic**: 数据库迁移工具Alembic的配置和历史版本。
      - **versions**: Alembic数据库迁移脚本。
    - **api**: API路由和业务逻辑。
      - **routes**: API路由定义。
    - **core**: 核心模块，如配置、数据库连接等。
    - **email-templates**: 邮件模板。
      - **build**: 编译后的邮件模板文件。
      - **src**: 原始邮件模板源代码。
    - **tests**: 单元测试和集成测试。
      - **api**: API测试。
        - **routes**: 路由相关的测试。
      - **crud**: CRUD操作的测试。
      - **scripts**: 脚本测试。
      - **utils**: 工具函数测试。
  - **scripts**: 自定义脚本，如部署、构建等。
- **frontend**: 前端React应用源代码。
  - **public**: 公共静态资源。
    - **assets**: 静态资源，如CSS、JavaScript和图像。
      - **images**: 图像资源。
  - **src**: 源代码。
    - **client**: 客户端核心逻辑。
      - **core**: 客户端核心模块。
    - **components**: React组件。
      - **Admin**: 管理员界面组件。
      - **Common**: 共享组件。
      - **Items**: 物品相关组件。
      - **UserSettings**: 用户设置组件。
    - **hooks**: 自定义React hooks。
    - **routes**: 路由配置。
      - **_layout**: 布局组件，用于包裹页面。
  - **tests**: 前端测试。
    - **utils**: 测试工具和辅助函数。
- **hooks**: Git钩子或其他预处理脚本。
- **img**: 图像资源，可能用于文档或示例。
- **scripts**: 项目级别的脚本，可能用于构建、清理等。
# Full Stack FastAPI Template

<a href="https://github.com/tiangolo/full-stack-fastapi-template/actions?query=workflow%3ATest" target="_blank"><img src="https://github.com/tiangolo/full-stack-fastapi-template/workflows/Test/badge.svg" alt="Test"></a>
<a href="https://coverage-badge.samuelcolvin.workers.dev/redirect/tiangolo/full-stack-fastapi-template" target="_blank"><img src="https://coverage-badge.samuelcolvin.workers.dev/tiangolo/full-stack-fastapi-template.svg" alt="Coverage"></a>

## Technology Stack and Features

- ⚡ [**FastAPI**](https://fastapi.tiangolo.com) for the Python backend API.
    - 🧰 [SQLModel](https://sqlmodel.tiangolo.com) for the Python SQL database interactions (ORM).
    - 🔍 [Pydantic](https://docs.pydantic.dev), used by FastAPI, for the data validation and settings management.
    - 💾 [PostgreSQL](https://www.postgresql.org) as the SQL database.
- 🚀 [React](https://react.dev) for the frontend.
    - 💃 Using TypeScript, hooks, Vite, and other parts of a modern frontend stack.
    - 🎨 [Chakra UI](https://chakra-ui.com) for the frontend components.
    - 🤖 An automatically generated frontend client.
    - 🦇 Dark mode support.
- 🐋 [Docker Compose](https://www.docker.com) for development and production.
- 🔒 Secure password hashing by default.
- 🔑 JWT (JSON Web Token) authentication.
- 📫 Email based password recovery.
- ✅ Tests with [Pytest](https://pytest.org).
- 📞 [Traefik](https://traefik.io) as a reverse proxy / load balancer.
- 🚢 Deployment instructions using Docker Compose, including how to set up a frontend Traefik proxy to handle automatic HTTPS certificates.
- 🏭 CI (continuous integration) and CD (continuous deployment) based on GitHub Actions.

### Dashboard Login
### 仪表板登录

[![API docs](img/login.png)](https://github.com/tiangolo/full-stack-fastapi-template)

### Dashboard - Admin
### 仪表板 - 管理员

[![API docs](img/dashboard.png)](https://github.com/tiangolo/full-stack-fastapi-template)

### Dashboard - Create User
### 仪表板 - 创建用户

[![API docs](img/dashboard-create.png)](https://github.com/tiangolo/full-stack-fastapi-template)

### Dashboard - Items
### 仪表板 - 项目

[![API docs](img/dashboard-items.png)](https://github.com/tiangolo/full-stack-fastapi-template)

### Dashboard - User Settings
### 仪表板 - 用户设置

[![API docs](img/dashboard-user-settings.png)](https://github.com/tiangolo/full-stack-fastapi-template)

### Dashboard - Dark Mode
### 仪表板 - 深色模式

[![API docs](img/dashboard-dark.png)](https://github.com/tiangolo/full-stack-fastapi-template)

### Interactive API Documentation
### 交互式 API 文档

[![API docs](img/docs.png)](https://github.com/tiangolo/full-stack-fastapi-template)

## How To Use It
## 如何使用

You can **just fork or clone** this repository and use it as is.

✨ It just works. ✨

### How to Use a Private Repository
### 如何使用私有仓库

If you want to have a private repository, GitHub won't allow you to simply fork it as it doesn't allow changing the visibility of forks.

But you can do the following:

- Create a new GitHub repo, for example `my-full-stack`.
- Clone this repository manually, set the name with the name of the project you want to use, for example `my-full-stack`:

```bash
git clone git@github.com:tiangolo/full-stack-fastapi-template.git my-full-stack
```

- Enter into the new directory:

```bash
cd my-full-stack
```

- Set the new origin to your new repository, copy it from the GitHub interface, for example:

```bash
git remote set-url origin git@github.com:octocat/my-full-stack.git
```

- Add this repo as another "remote" to allow you to get updates later:

```bash
git remote add upstream git@github.com:tiangolo/full-stack-fastapi-template.git
```

- Push the code to your new repository:

```bash
git push -u origin master
```

### Update From the Original Template
### 从原始模板更新

After cloning the repository, and after doing changes, you might want to get the latest changes from this original template.

- Make sure you added the original repository as a remote, you can check it with:

```bash
git remote -v

origin    git@github.com:octocat/my-full-stack.git (fetch)
origin    git@github.com:octocat/my-full-stack.git (push)
upstream    git@github.com:tiangolo/full-stack-fastapi-template.git (fetch)
upstream    git@github.com:tiangolo/full-stack-fastapi-template.git (push)
```

- Pull the latest changes without merging:

```bash
git pull --no-commit upstream master
```

This will download the latest changes from this template without committing them, that way you can check everything is right before committing.

- If there are conflicts, solve them in your editor.

- Once you are done, commit the changes:

```bash
git merge --continue
```

### Configure

You can then update configs in the `.env` files to customize your configurations.

Before deploying it, make sure you change at least the values for:

- `SECRET_KEY`
- `FIRST_SUPERUSER_PASSWORD`
- `POSTGRES_PASSWORD`

You can (and should) pass these as environment variables from secrets.

Read the [deployment.md](./deployment.md) docs for more details.

### Generate Secret Keys
### 生成密钥

Some environment variables in the `.env` file have a default value of `changethis`.

You have to change them with a secret key, to generate secret keys you can run the following command:

```bash
python -c "import secrets; print(secrets.token_urlsafe(32))"
```

Copy the content and use that as password / secret key. And run that again to generate another secure key.

## How To Use It - Alternative With Copier

This repository also supports generating a new project using [Copier](https://copier.readthedocs.io).

It will copy all the files, ask you configuration questions, and update the `.env` files with your answers.

### Install Copier

You can install Copier with:

```bash
pip install copier
```

Or better, if you have [`pipx`](https://pipx.pypa.io/), you can run it with:

```bash
pipx install copier
```

**Note**: If you have `pipx`, installing copier is optional, you could run it directly.

### Generate a Project With Copier

Decide a name for your new project's directory, you will use it below. For example, `my-awesome-project`.

Go to the directory that will be the parent of your project, and run the command with your project's name:

```bash
copier copy https://github.com/tiangolo/full-stack-fastapi-template my-awesome-project --trust
```

If you have `pipx` and you didn't install `copier`, you can run it directly:

```bash
pipx run copier copy https://github.com/tiangolo/full-stack-fastapi-template my-awesome-project --trust
```

**Note** the `--trust` option is necessary to be able to execute a [post-creation script](https://github.com/tiangolo/full-stack-fastapi-template/blob/master/.copier/update_dotenv.py) that updates your `.env` files.

### Input Variables

Copier will ask you for some data, you might want to have at hand before generating the project.

But don't worry, you can just update any of that in the `.env` files afterwards.

The input variables, with their default values (some auto generated) are:

- `project_name`: (default: `"FastAPI Project"`) The name of the project, shown to API users (in .env).
- `stack_name`: (default: `"fastapi-project"`) The name of the stack used for Docker Compose labels and project name (no spaces, no periods) (in .env).
- `secret_key`: (default: `"changethis"`) The secret key for the project, used for security, stored in .env, you can generate one with the method above.
- `first_superuser`: (default: `"admin@example.com"`) The email of the first superuser (in .env).
- `first_superuser_password`: (default: `"changethis"`) The password of the first superuser (in .env).
- `smtp_host`: (default: "") The SMTP server host to send emails, you can set it later in .env.
- `smtp_user`: (default: "") The SMTP server user to send emails, you can set it later in .env.
- `smtp_password`: (default: "") The SMTP server password to send emails, you can set it later in .env.
- `emails_from_email`: (default: `"info@example.com"`) The email account to send emails from, you can set it later in .env.
- `postgres_password`: (default: `"changethis"`) The password for the PostgreSQL database, stored in .env, you can generate one with the method above.
- `sentry_dsn`: (default: "") The DSN for Sentry, if you are using it, you can set it later in .env.

## Backend Development
## 后端开发

Backend docs: [backend/README.md](./backend/README.md).

## Frontend Development
## 前端开发

Frontend docs: [frontend/README.md](./frontend/README.md).

## Deployment
## 部署

Deployment docs: [deployment.md](./deployment.md).

## Development

General development docs: [development.md](./development.md).

This includes using Docker Compose, custom local domains, `.env` configurations, etc.

## Release Notes
## 发布说明

Check the file [release-notes.md](./release-notes.md).

## License

The Full Stack FastAPI Template is licensed under the terms of the MIT license.