Shurly

Shurly，这是一个具有API管理的URL缩短器

特性

• 通过REST风格的API管理目标
• 永久/临时重定向；永久重定向在创建后不能更改
• 为目标添加注释以跟踪目标的使用情况
• 跟踪目标上的所有点击，包括用户代理和IP地址（如果可能）
• 所有创意/破坏性管理操作的审计日志

快速使用

# Create destination
curl -v -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer tokentokentoken' \
    -d '{ "slug": "the-one", "url": "https://www.example.com/" }' \
    https://127.0.0.1:7000/api/destinations

# The redirect
curl -v https://127.0.0.1:7000/the-one

# Response:
# < HTTP/2 307
# < Location: https://www.example.com/

入门

设置PostgreSQL数据库

实际上运行Shurly需要一个数据库，即实际的数据库。这可以单独设置，或者可以使用Docker Compose设置，这将运行一个PostgreSQL服务器容器。最后，Shurly需要一个有效的DATABASE_URL。

有几种运行方式，具体取决于您的偏好

Shurly可以直接使用cargo install shurly安装，这将在一个路径中放置一个shurly二进制文件（如果Cargo安装直接在您的PATH中）。

当然，自己构建也是可能的，有一些额外的选项。首先，您需要克隆仓库。

git clone [email protected]:workplacebuddy/shurley.git

然后，只需执行cargo run即可。如果您更喜欢Docker，构建也是可能的。

docker build --tag shurly .

运行方法与所有Docker容器相同。

docker run --rm --interactive --tty --publish 7000:7000 shurly .

# for short
docker run --rm -it -p 7000:7000 shurly .

使用方法

Shurly提供了一个非常简单的REST风格的接口来管理目标和其属性。

根目录

不匹配API路由的所有内容都将由根作为后备处理，该根将根据其路径查找目标，要么重定向到该目标，要么显示404。

重定向是基于目标的isPermanent属性完成的；永久重定向使用308（永久重定向）状态码，临时重定向使用307（临时重定向）重定向。两者都将设置Location头到相关URL。

管理

只有授权用户可以管理目标，并需要获取令牌才能访问其他API端点。

curl -v -H 'Content-Type: application/json' \
    -d '{ "username": "admin", "password": "verysecret" }' \
    https://127.0.0.1:7000/api/users/token

# < { "data": { "type": "Bearer", "access_token": "some token" } }

要创建目标，可以将带有负载的请求发送到/api/destinations URL。

curl -v -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer tokentokentoken' \
    -d '{ "slug": "some-easy-name", "url": "https://www.example.com/" }' \
    https://127.0.0.1:7000/api/destinations

# < { "data": { "id": "<uuid>", "slug": "some-easy-name" ... } }

可选地，您可以发送isPermanent属性，以指示应使用哪种类型的重定向。创建后，永久重定向不能更改。

更新目标的方式相同。

curl -v XPATCH -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer tokentokentoken' \
    -d '{ "url": "https://www.example.com/", "isPermanent": true }' \
    https://127.0.0.1:7000/api/destinations/<uuid>

# < { "data": { "id": "<uuid>", "slug": "some-easy-name" ... } }

slug在创建后不能更改。将isPermanent标志更改为true是可能的，反之则不行。当isPermanent为true时，更新url将失败。

要删除目标，有一个可用的DELETE端点。

curl -v XDELETE \
    -H 'Authorization: Bearer tokentokentoken' \
    https://127.0.0.1:7000/api/destinations/<uuid>

这将软删除目标；使用相同slug创建新的目标是不可能的：创新是关键。

还有更多交互可用，但这应该能让您开始。

# Directly with Cargo
cargo install shurly

# Run locally
cargo run

# Docker build (running is the same)
docker build --tag shurly .

简单的docker compose up即可开始。使用docker compose up --build重新构建Shurly镜像。

Docker Compose设置还运行Shurly的Docker版本，这可能不适合快速开发迭代。Docker Compose提供选项，只运行设置中的单个容器。

# `the-data` is the name of the PostgreSQL service
docker compose up the-data

在没有Docker运行时，需要设置一个DATABASE_URL环境变量。

预构建Docker镜像

对于那些喜欢使用Docker但不想麻烦构建镜像的人来说，预构建镜像可用

• ghcr.io/workplacebuddy/shurly:master
• 更多信息及标签请在此处查看：https://github.com/workplacebuddy/shurly/pkgs/container/shurly

配置

使用默认设置运行时，缺失的配置将有一个合理的默认值或自动生成。对于开发来说这很好，但在生产环境中有不同的要求。所有配置都通过环境变量完成。

设置日志记录

tracing用于所有日志记录（可选）

RUST_LOG=shurly=debug,tower_http=debug

编码秘密

用于编码JWT令牌的秘密，确保它足够长（可选，默认：一些随机字符串）

JWT_SECRET=

数据库连接

PostgreSQL服务器的连接字符串。在运行Docker Compose设置时，这将提供。

DATABASE_URL=

实际的服务器

为了与外界通信，Shurly需要绑定到地址以接受连接。

# Address for Shurly to bind to
ADDRESS=0.0.0.0:7000

# Override just the port to run Shurly on
PORT=7000

初始用户凭据

在首次运行时，会创建一个用户，并使用一些随机生成的凭据；这些凭据将显示在服务器日志中。初始凭据可以通过INITIAL_USERNAME和INITIAL_PASSWORD环境变量进行更改。使用这些变量时，它们不会输出到日志。

• INITIAL_USERNAME：首次运行的第一个用户的用户名（可选，默认：一些UUIDv4）
• INITIAL_PASSWORD：首次运行的第一个用户的密码（可选，默认：一些随机字符串）

环境变量可以设置在一个.env文件中，有关示例，请参阅.env.default。

PostgreSQL数据库迁移

Shurly使用SQLx进行所有PostgreSQL数据库交互，迁移在启动时自动运行。

迁移文件位于 ./migrations 目录中，并按文件名排序。

开发

使用迁移可能会有点麻烦，没有有效的数据库连接和正确的模式，项目无法正确构建。Docker镜像使用环境变量 SQLX_OFFLINE=true 来使用 sqlx-data.json 文件中的缓存数据。运行编译后的Shurly版本将自动运行迁移 —— 编译它才是关键 :)

使用 SQLx CLI为处理迁移添加了一些便利功能。

• 使用以下命令安装： cargo install sqlx-cli，或者使用 其他选项。
• 确保设置了环境变量 DATABASE_URL
• 开始： cargo sqlx migrate run
• 撤销： cargo sqlx migrate revert

Rust版本

Shurly在Rust版本1.65（稳定版和测试版）上进行了测试。Docker镜像使用rust:1.65-slim作为基础镜像创建。

要做的事情（也许）

• 公开一些统计信息的端点，数据已经捕获
• 在 hits 中跟踪传入的参数，也许吧？
• 为目的地添加别名，以便原始的点击数
• 一个相当吸引人的404页面，或者一个默认目的地？
• 所有API端点的描述
• 在实际数据库上运行测试

而且，不要叫我Shirly。